@serfab/cadre-host 0.7.1

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

@@ -0,0 +1,253 @@
+import { describe, expect, it } from 'vitest';
+
+import { DdnsUpdater } from '../ddns/updater.js';
+import type { DdnsProvider } from '../ddns/index.js';
+import type { SecretsStore } from '../secrets/index.js';
+import { ddnsAccount } from '../secrets/index.js';
+import { NatError, type NatDdnsSettings } from '../types.js';
+
+function makeSecrets(seed: Record<string, string> = {}): SecretsStore {
+  const map = new Map(Object.entries(seed));
+  return {
+    async set(a, v) { map.set(a, v); },
+    async get(a) { return map.has(a) ? map.get(a)! : null; },
+    async delete(a) { return map.delete(a); },
+    async list() { return Array.from(map.keys()); },
+  };
+}
+
+function makeProvider(overrides: Partial<DdnsProvider> = {}): DdnsProvider & {
+  calls: Array<{ hostname: string; ip: string; config: Record<string, string> }>;
+  shouldThrow: Error | null;
+} {
+  const calls: Array<{ hostname: string; ip: string; config: Record<string, string> }> = [];
+  let shouldThrow: Error | null = null;
+  return {
+    id: 'duckdns',
+    displayName: 'DuckDNS',
+    configFields: [{ key: 'token', label: 'DuckDNS token', secret: true }],
+    async update(config, hostname, ip) {
+      calls.push({ hostname, ip, config });
+      if (shouldThrow) throw shouldThrow;
+    },
+    ...overrides,
+    get calls() { return calls; },
+    get shouldThrow() { return shouldThrow; },
+    set shouldThrow(e: Error | null) { shouldThrow = e; },
+  } as DdnsProvider & {
+    calls: Array<{ hostname: string; ip: string; config: Record<string, string> }>;
+    shouldThrow: Error | null;
+  };
+}
+
+function fakeIntervalTimers(): {
+  setInterval: (fn: () => void, ms: number) => NodeJS.Timeout;
+  clearInterval: (h: NodeJS.Timeout) => void;
+  fire(): Promise<void>;
+  cleared: number;
+} {
+  let cb: (() => void) | null = null;
+  let cleared = 0;
+  return {
+    setInterval: (fn) => { cb = fn; return { _id: 1 } as unknown as NodeJS.Timeout; },
+    clearInterval: () => { cb = null; cleared++; },
+    async fire() { const f = cb; if (f) { f(); await new Promise((r) => setTimeout(r, 0)); } },
+    get cleared() { return cleared; },
+  };
+}
+
+const baseSettings: NatDdnsSettings = {
+  providerId: 'duckdns',
+  hostname: 'foo.duckdns.org',
+  externallyManaged: false,
+  intervalMs: 60_000,
+};
+
+describe('DdnsUpdater', () => {
+  it('no-op when externallyManaged', async () => {
+    const provider = makeProvider();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    let ip: string | null = '1.2.3.4';
+    const u = new DdnsUpdater({
+      settings: { ...baseSettings, externallyManaged: true },
+      secrets,
+      getExternalIp: () => ip,
+      resolveProvider: () => provider,
+      ...fakeIntervalTimers(),
+    });
+    await u.start();
+    expect(provider.calls).toHaveLength(0);
+  });
+
+  it('no-op when providerId is null', async () => {
+    const provider = makeProvider();
+    const u = new DdnsUpdater({
+      settings: { ...baseSettings, providerId: null },
+      secrets: makeSecrets(),
+      getExternalIp: () => '1.2.3.4',
+      resolveProvider: () => provider,
+      ...fakeIntervalTimers(),
+    });
+    await u.start();
+    expect(provider.calls).toHaveLength(0);
+  });
+
+  it('pushes the IP on start, records lastUpdateOk=true', async () => {
+    const provider = makeProvider();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets,
+      getExternalIp: () => '1.2.3.4',
+      resolveProvider: () => provider,
+      ...fakeIntervalTimers(),
+    });
+    const outcome = await u.start();
+    expect(outcome.ok).toBe(true);
+    expect(outcome.ip).toBe('1.2.3.4');
+    expect(provider.calls).toEqual([
+      { hostname: 'foo.duckdns.org', ip: '1.2.3.4', config: { token: 'T' } },
+    ]);
+    const status = u.getStatus();
+    expect(status.lastUpdateOk).toBe(true);
+    expect(status.lastError).toBeNull();
+  });
+
+  it('does not re-push when IP is unchanged', async () => {
+    const provider = makeProvider();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    const timers = fakeIntervalTimers();
+    let ip = '1.2.3.4';
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets,
+      getExternalIp: () => ip,
+      resolveProvider: () => provider,
+      setInterval: timers.setInterval,
+      clearInterval: timers.clearInterval,
+    });
+    await u.start();
+    expect(provider.calls).toHaveLength(1);
+
+    await timers.fire();
+    expect(provider.calls).toHaveLength(1);
+
+    // Change the IP — next tick should call.
+    ip = '5.6.7.8';
+    await timers.fire();
+    expect(provider.calls).toHaveLength(2);
+    expect(provider.calls[1]?.ip).toBe('5.6.7.8');
+  });
+
+  it('records error but keeps timer running on provider throw', async () => {
+    const provider = makeProvider();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    const timers = fakeIntervalTimers();
+    let ip = '1.2.3.4';
+
+    provider.shouldThrow = new NatError('ddns_update_failed', 'boom');
+
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets,
+      getExternalIp: () => ip,
+      resolveProvider: () => provider,
+      setInterval: timers.setInterval,
+      clearInterval: timers.clearInterval,
+    });
+
+    await u.start();
+    expect(u.getStatus().lastUpdateOk).toBe(false);
+    expect(u.getStatus().lastError).toContain('boom');
+
+    // Provider stops throwing — next change → success
+    provider.shouldThrow = null;
+    ip = '5.6.7.8';
+    await timers.fire();
+
+    expect(provider.calls.length).toBeGreaterThanOrEqual(2);
+    expect(u.getStatus().lastUpdateOk).toBe(true);
+    expect(u.getStatus().lastError).toBeNull();
+  });
+
+  it('reports ddns_credentials_missing when secrets are empty', async () => {
+    const provider = makeProvider();
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets: makeSecrets(),
+      getExternalIp: () => '1.2.3.4',
+      resolveProvider: () => provider,
+      ...fakeIntervalTimers(),
+    });
+    const outcome = await u.start();
+    expect(outcome.ok).toBe(false);
+    expect(outcome.error).toMatch(/credential/i);
+    expect(provider.calls).toHaveLength(0);
+  });
+
+  it('forceUpdate ignores unchanged-IP shortcut', async () => {
+    const provider = makeProvider();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets,
+      getExternalIp: () => '1.2.3.4',
+      resolveProvider: () => provider,
+      ...fakeIntervalTimers(),
+    });
+    await u.start();
+    await u.forceUpdate();
+    expect(provider.calls).toHaveLength(2);
+  });
+
+  it('stop() clears the timer; idempotent', async () => {
+    const provider = makeProvider();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    const timers = fakeIntervalTimers();
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets,
+      getExternalIp: () => '1.2.3.4',
+      resolveProvider: () => provider,
+      setInterval: timers.setInterval,
+      clearInterval: timers.clearInterval,
+    });
+    await u.start();
+    u.stop();
+    u.stop();
+    expect(timers.cleared).toBe(1);
+  });
+
+  it('updateSettings restarts with new config', async () => {
+    const provider = makeProvider();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets,
+      getExternalIp: () => '1.2.3.4',
+      resolveProvider: () => provider,
+      ...fakeIntervalTimers(),
+    });
+    await u.start();
+    expect(provider.calls).toHaveLength(1);
+
+    await u.updateSettings({ ...baseSettings, hostname: 'bar.duckdns.org' });
+    expect(provider.calls).toHaveLength(2);
+    expect(provider.calls[1]?.hostname).toBe('bar.duckdns.org');
+  });
+
+  it('records "external IP unknown" when getExternalIp returns null', async () => {
+    const provider = makeProvider();
+    const u = new DdnsUpdater({
+      settings: baseSettings,
+      secrets: makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' }),
+      getExternalIp: () => null,
+      resolveProvider: () => provider,
+      ...fakeIntervalTimers(),
+    });
+    const outcome = await u.start();
+    expect(outcome.attempted).toBe(false);
+    expect(outcome.error).toMatch(/unknown/i);
+    expect(provider.calls).toHaveLength(0);
+  });
+});

package/src/nat/__tests__/external-ip.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+
+import { ExternalIpDetector, isPlausibleIp } from '../external-ip.js';
+
+function makeFetchSequence(responses: Array<{ ok: boolean; body: string }>): typeof fetch {
+  let i = 0;
+  return (async () => {
+    const r = responses[i++] ?? { ok: false, body: '' };
+    return {
+      ok: r.ok,
+      status: r.ok ? 200 : 500,
+      async text() { return r.body; },
+    } as unknown as Response;
+  }) as typeof fetch;
+}
+
+describe('isPlausibleIp()', () => {
+  it('accepts IPv4', () => {
+    expect(isPlausibleIp('1.2.3.4')).toBe(true);
+    expect(isPlausibleIp('255.255.255.255')).toBe(true);
+  });
+  it('rejects bad IPv4', () => {
+    expect(isPlausibleIp('256.0.0.1')).toBe(false);
+    expect(isPlausibleIp('1.2.3')).toBe(false);
+  });
+  it('accepts IPv6 liberally', () => {
+    expect(isPlausibleIp('::1')).toBe(true);
+    expect(isPlausibleIp('2001:db8::1')).toBe(true);
+  });
+  it('rejects junk', () => {
+    expect(isPlausibleIp('not an ip')).toBe(false);
+    expect(isPlausibleIp('')).toBe(false);
+  });
+});
+
+describe('ExternalIpDetector', () => {
+  it('returns null routerIp when no probe configured', async () => {
+    const det = new ExternalIpDetector({
+      fetch: makeFetchSequence([{ ok: true, body: '1.2.3.4' }]),
+      publicIpUrls: ['https://example.test'],
+    });
+    const r = await det.detect();
+    expect(r.routerIp).toBeNull();
+    expect(r.publicIp).toBe('1.2.3.4');
+    expect(r.cgnat).toBe(false);
+  });
+
+  it('detects CGNAT when router and public IP disagree', async () => {
+    const det = new ExternalIpDetector({
+      routerProbe: async () => '100.64.0.5',  // CGNAT space — fine for testing
+      fetch: makeFetchSequence([{ ok: true, body: '203.0.113.10' }]),
+      publicIpUrls: ['https://example.test'],
+    });
+    const r = await det.detect();
+    expect(r.routerIp).toBe('100.64.0.5');
+    expect(r.publicIp).toBe('203.0.113.10');
+    expect(r.cgnat).toBe(true);
+  });
+
+  it('does NOT flag CGNAT when IPs agree', async () => {
+    const det = new ExternalIpDetector({
+      routerProbe: async () => '1.2.3.4',
+      fetch: makeFetchSequence([{ ok: true, body: '1.2.3.4' }]),
+      publicIpUrls: ['https://example.test'],
+    });
+    const r = await det.detect();
+    expect(r.cgnat).toBe(false);
+  });
+
+  it('does NOT flag CGNAT when one probe fails', async () => {
+    const det = new ExternalIpDetector({
+      routerProbe: async () => '1.2.3.4',
+      fetch: makeFetchSequence([{ ok: false, body: '' }]),
+      publicIpUrls: ['https://example.test'],
+    });
+    const r = await det.detect();
+    expect(r.routerIp).toBe('1.2.3.4');
+    expect(r.publicIp).toBeNull();
+    expect(r.cgnat).toBe(false);
+  });
+
+  it('falls through public probe URLs until one succeeds', async () => {
+    const det = new ExternalIpDetector({
+      fetch: makeFetchSequence([
+        { ok: false, body: '' },
+        { ok: true, body: '8.8.8.8' },
+      ]),
+      publicIpUrls: ['https://a.test', 'https://b.test'],
+    });
+    const r = await det.detect();
+    expect(r.publicIp).toBe('8.8.8.8');
+  });
+
+  it('treats router probe throw as null', async () => {
+    const det = new ExternalIpDetector({
+      routerProbe: async () => { throw new Error('upnp not reachable'); },
+      fetch: makeFetchSequence([{ ok: true, body: '1.2.3.4' }]),
+      publicIpUrls: ['https://a.test'],
+    });
+    const r = await det.detect();
+    expect(r.routerIp).toBeNull();
+    expect(r.publicIp).toBe('1.2.3.4');
+    expect(r.cgnat).toBe(false);
+  });
+
+  it('rejects implausible router-probe IP', async () => {
+    const det = new ExternalIpDetector({
+      routerProbe: async () => 'not-an-ip',
+      fetch: makeFetchSequence([{ ok: true, body: '1.2.3.4' }]),
+      publicIpUrls: ['https://a.test'],
+    });
+    const r = await det.detect();
+    expect(r.routerIp).toBeNull();
+  });
+
+  it('rejects non-IP public-service body', async () => {
+    const det = new ExternalIpDetector({
+      fetch: makeFetchSequence([{ ok: true, body: '<html>error</html>' }]),
+      publicIpUrls: ['https://a.test'],
+    });
+    const r = await det.detect();
+    expect(r.publicIp).toBeNull();
+  });
+});

package/src/nat/__tests__/nat-service.test.ts

@@ -0,0 +1,305 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { NatService, createNatHandlers } from '../nat-service.js';
+import { ExternalIpDetector } from '../external-ip.js';
+import type { PortMapper, PortMappingResult } from '../port-mapper.js';
+import type { SecretsStore } from '../secrets/index.js';
+import { ddnsAccount } from '../secrets/index.js';
+import type { CadreNodeLike } from '../nat-service.js';
+
+class StubMapper implements PortMapper {
+  mapCalls = 0;
+  unmapCalls = 0;
+  stopCalls = 0;
+  externalIpValue: string | null = '203.0.113.10';
+  mapFails = false;
+  async map(o: { externalPort: number; internalPort: number; protocol?: 'tcp' | 'udp'; ttlMs?: number }): Promise<PortMappingResult> {
+    this.mapCalls++;
+    if (this.mapFails) throw new Error('router refused');
+    return {
+      mode: 'auto-upnp',
+      externalIp: this.externalIpValue,
+      externalPort: o.externalPort,
+      internalPort: o.internalPort,
+      protocol: o.protocol ?? 'tcp',
+      leaseExpiresAt: new Date(Date.now() + (o.ttlMs ?? 60_000)),
+    };
+  }
+  async verify() { return true; }
+  async externalIp() { return this.externalIpValue; }
+  async unmap() { this.unmapCalls++; }
+  async stop() { this.stopCalls++; }
+}
+
+function makeSecrets(seed: Record<string, string> = {}): SecretsStore {
+  const m = new Map(Object.entries(seed));
+  return {
+    async set(a, v) { m.set(a, v); },
+    async get(a) { return m.has(a) ? m.get(a)! : null; },
+    async delete(a) { return m.delete(a); },
+    async list() { return [...m.keys()]; },
+  };
+}
+
+function makeNode(peerId = '12D3KooWHost', addrs: string[] = ['/ip4/192.168.1.10/tcp/4001']): CadreNodeLike {
+  return {
+    getPeerId: () => peerId,
+    getMultiaddrs: () => addrs,
+  };
+}
+
+function makeDetector(opts: { router?: string | null; pub?: string | null }): ExternalIpDetector {
+  return new ExternalIpDetector({
+    routerProbe: opts.router === undefined ? undefined : async () => opts.router ?? null,
+    fetch: (async () => ({
+      ok: opts.pub != null,
+      status: opts.pub != null ? 200 : 500,
+      async text() { return opts.pub ?? ''; },
+    })) as unknown as typeof fetch,
+    publicIpUrls: ['https://stub.test'],
+  });
+}
+
+let tmpRoot: string;
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nat-svc-'));
+});
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('NatService', () => {
+  it('start() runs port mapping, detects IP, status reflects auto-upnp', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ router: '203.0.113.10', pub: '203.0.113.10' }),
+    });
+    await svc.start();
+    const s = svc.getStatus();
+    expect(s.portMode).toBe('auto-upnp');
+    expect(s.externalPort).toBe(4001);
+    expect(s.externalIp).toBe('203.0.113.10');
+    expect(s.directReachability).toBe('reachable');
+    expect(mapper.mapCalls).toBe(1);
+  });
+
+  it('detects CGNAT and flags directReachability=cgnat', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ router: '100.64.0.5', pub: '203.0.113.10' }),
+    });
+    await svc.start();
+    const s = svc.getStatus();
+    expect(s.cgnatDetected).toBe(true);
+    expect(s.directReachability).toBe('cgnat');
+  });
+
+  it('flips portMode to failed when mapper throws', async () => {
+    const mapper = new StubMapper();
+    mapper.mapFails = true;
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    expect(svc.getStatus().portMode).toBe('failed');
+    expect(svc.getStatus().directReachability).toBe('unreachable');
+  });
+
+  it('stop() unmaps and is idempotent', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    await svc.stop();
+    await svc.stop();
+    expect(mapper.unmapCalls).toBe(1);
+    expect(mapper.stopCalls).toBe(1);
+  });
+
+  it('getInviteAddresses → dns4 when DDNS configured + reachable', async () => {
+    const mapper = new StubMapper();
+    const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode('12D3KooWHost'),
+      secretsStore: secrets,
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    await svc.putDdns({
+      providerId: 'duckdns',
+      hostname: 'foo.duckdns.org',
+      config: { token: 'T' },
+    });
+    const addrs = await svc.getInviteAddresses();
+    expect(addrs).toEqual(['/dns4/foo.duckdns.org/tcp/4001/p2p/12D3KooWHost']);
+  });
+
+  it('getInviteAddresses → ip4 when reachable but no DDNS', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode('12D3KooWHost'),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '203.0.113.42' }),
+    });
+    await svc.start();
+    const addrs = await svc.getInviteAddresses();
+    expect(addrs).toEqual(['/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWHost']);
+  });
+
+  it('getInviteAddresses → libp2p fallback when unreachable', async () => {
+    const mapper = new StubMapper();
+    mapper.mapFails = true;
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode('12D3KooWHost', ['/ip4/10.0.0.5/tcp/4001']),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: null }),
+    });
+    await svc.start();
+    const addrs = await svc.getInviteAddresses();
+    expect(addrs).toEqual(['/ip4/10.0.0.5/tcp/4001/p2p/12D3KooWHost']);
+  });
+
+  it('putDdns persists secrets and updates status', async () => {
+    const secrets = makeSecrets();
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: secrets,
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    const status = await svc.putDdns({
+      providerId: 'duckdns',
+      hostname: 'h.duckdns.org',
+      config: { token: 'TOK' },
+    });
+    expect(status.ddns.providerId).toBe('duckdns');
+    expect(status.ddns.hostname).toBe('h.duckdns.org');
+    expect(await secrets.get(ddnsAccount('duckdns', 'token'))).toBe('TOK');
+  });
+
+  it('putDdns with unknown provider → ddns_provider_unknown', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    await expect(svc.putDdns({
+      providerId: 'no-such-provider',
+      hostname: 'x',
+      config: {},
+    })).rejects.toMatchObject({ code: 'ddns_provider_unknown' });
+  });
+
+  it('putSettings can disable UPnP and re-enable it', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    expect(mapper.mapCalls).toBe(1);
+
+    let s = await svc.putSettings({ upnpEnabled: false });
+    expect(s.portMode).toBe('disabled');
+
+    s = await svc.putSettings({ upnpEnabled: true });
+    expect(s.portMode).toBe('auto-upnp');
+    expect(mapper.mapCalls).toBeGreaterThanOrEqual(2);
+  });
+
+  it('testReachability re-runs IP detect and updates lastTestedAt', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    expect(svc.getStatus().lastTestedAt).toBeNull();
+    await svc.testReachability();
+    expect(svc.getStatus().lastTestedAt).not.toBeNull();
+  });
+
+  it('listDdnsProviders returns at least DuckDNS', () => {
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    const providers = svc.listDdnsProviders();
+    const duck = providers.find((p) => p.id === 'duckdns');
+    expect(duck).toBeDefined();
+    expect(duck!.configFields[0]).toMatchObject({ key: 'token', secret: true });
+  });
+});
+
+describe('createNatHandlers', () => {
+  it('every handler delegates to the service', async () => {
+    const mapper = new StubMapper();
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: mapper,
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    const h = createNatHandlers(svc);
+
+    expect((await h.getStatus()).portMode).toBe('auto-upnp');
+    expect((await h.listDdnsProviders()).find((p) => p.id === 'duckdns')).toBeDefined();
+
+    const status = await h.testReachability();
+    expect(status.lastTestedAt).not.toBeNull();
+
+    const after = await h.putSettings({ externalPort: 4002 });
+    expect(after.externalPort).toBe(4002);
+
+    const ddnsStatus = await h.putDdns({
+      providerId: 'duckdns',
+      hostname: 'a.duckdns.org',
+      config: { token: 'T' },
+    });
+    expect(ddnsStatus.ddns.hostname).toBe('a.duckdns.org');
+  });
+});