@serfab/cadre-host 0.7.1

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

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { NatStore } from '../nat-store.js';
+import { NatError } from '../types.js';
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nat-store-'));
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('NatStore', () => {
+  it('returns defaults when file is missing', () => {
+    const store = new NatStore(tmpRoot);
+    const s = store.load();
+    expect(s.externalPort).toBe(4001);
+    expect(s.internalPort).toBe(4001);
+    expect(s.upnpEnabled).toBe(true);
+    expect(s.ddns.providerId).toBeNull();
+    expect(s.ddns.externallyManaged).toBe(false);
+    expect(s.ddns.intervalMs).toBe(5 * 60 * 1000);
+  });
+
+  it('persists and reloads settings atomically', () => {
+    const store = new NatStore(tmpRoot);
+    store.update({ externalPort: 4002, upnpEnabled: false });
+
+    expect(existsSync(join(tmpRoot, 'nat.json'))).toBe(true);
+    expect(existsSync(join(tmpRoot, 'nat.json.tmp'))).toBe(false);
+
+    const reread = new NatStore(tmpRoot);
+    const s = reread.load();
+    expect(s.externalPort).toBe(4002);
+    expect(s.upnpEnabled).toBe(false);
+  });
+
+  it('merges ddns subtree on update', () => {
+    const store = new NatStore(tmpRoot);
+    store.update({
+      ddns: {
+        providerId: 'duckdns',
+        hostname: 'foo.duckdns.org',
+        externallyManaged: false,
+        intervalMs: 60_000,
+      },
+    });
+
+    store.update({ ddns: { externallyManaged: true } as never });
+
+    const s = store.load();
+    expect(s.ddns.providerId).toBe('duckdns');
+    expect(s.ddns.hostname).toBe('foo.duckdns.org');
+    expect(s.ddns.externallyManaged).toBe(true);
+    expect(s.ddns.intervalMs).toBe(60_000);
+  });
+
+  it('persists version field', () => {
+    const store = new NatStore(tmpRoot);
+    store.update({ externalPort: 4001 });
+    const raw = JSON.parse(readFileSync(join(tmpRoot, 'nat.json'), 'utf8'));
+    expect(raw.version).toBe(1);
+  });
+
+  it('throws on malformed JSON rather than silently wiping', () => {
+    writeFileSync(join(tmpRoot, 'nat.json'), 'not json', 'utf8');
+    const store = new NatStore(tmpRoot);
+    expect(() => store.load()).toThrow(NatError);
+  });
+
+  it('rejects invalid port', () => {
+    const store = new NatStore(tmpRoot);
+    expect(() => store.update({ externalPort: 0 })).toThrow(NatError);
+    expect(() => store.update({ externalPort: 70000 })).toThrow(NatError);
+  });
+
+  it('rejects too-small interval', () => {
+    const store = new NatStore(tmpRoot);
+    expect(() => store.update({ ddns: { intervalMs: 500 } as never })).toThrow(NatError);
+  });
+
+  it('rejects empty string providerId/hostname', () => {
+    const store = new NatStore(tmpRoot);
+    expect(() => store.update({ ddns: { providerId: '' } as never })).toThrow(NatError);
+    expect(() => store.update({ ddns: { hostname: '' } as never })).toThrow(NatError);
+  });
+});

package/src/nat/__tests__/port-mapper.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { NatError } from '../types.js';
+import {
+  PortMapperService,
+  type PortMapper,
+  type PortMappingResult,
+} from '../port-mapper.js';
+
+interface FakeOpts {
+  mapShouldThrow?: Error;
+  verifyResult?: boolean;
+  verifyShouldThrow?: Error;
+  externalIp?: string | null;
+}
+
+function makeFakeMapper(initial: FakeOpts = {}): PortMapper & {
+  calls: { map: number; verify: number; unmap: number; stop: number };
+  options: FakeOpts;
+} {
+  const opts = { ...initial };
+  const calls = { map: 0, verify: 0, unmap: 0, stop: 0 };
+  return {
+    options: opts,
+    calls,
+    async map(o): Promise<PortMappingResult> {
+      calls.map++;
+      if (opts.mapShouldThrow) throw opts.mapShouldThrow;
+      return {
+        mode: 'auto-upnp',
+        externalIp: opts.externalIp ?? '203.0.113.1',
+        externalPort: o.externalPort,
+        internalPort: o.internalPort,
+        protocol: o.protocol ?? 'tcp',
+        leaseExpiresAt: new Date(Date.now() + (o.ttlMs ?? 60_000)),
+      };
+    },
+    async verify() {
+      calls.verify++;
+      if (opts.verifyShouldThrow) throw opts.verifyShouldThrow;
+      return opts.verifyResult ?? true;
+    },
+    async externalIp() {
+      return opts.externalIp ?? '203.0.113.1';
+    },
+    async unmap() {
+      calls.unmap++;
+    },
+    async stop() {
+      calls.stop++;
+    },
+  };
+}
+
+function fakeTimers(): {
+  setTimer: (fn: () => void, ms: number) => NodeJS.Timeout;
+  clearTimer: (h: NodeJS.Timeout) => void;
+  fire(): void;
+  pending: number;
+} {
+  let callback: (() => void) | null = null;
+  return {
+    setTimer: (fn) => {
+      callback = fn;
+      return {} as NodeJS.Timeout;
+    },
+    clearTimer: () => {
+      callback = null;
+    },
+    fire: () => {
+      const cb = callback;
+      callback = null;
+      cb?.();
+    },
+    get pending() { return callback ? 1 : 0; },
+  };
+}
+
+describe('PortMapperService', () => {
+  it('installs the mapping on start and records mode + externalIp', async () => {
+    const mapper = makeFakeMapper({ externalIp: '203.0.113.42' });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper,
+      externalPort: 4001,
+      internalPort: 4001,
+      setTimer: timers.setTimer,
+      clearTimer: timers.clearTimer,
+    });
+
+    await svc.start();
+    const state = svc.getState();
+    expect(state.mode).toBe('auto-upnp');
+    expect(state.routerExternalIp).toBe('203.0.113.42');
+    expect(state.externalPort).toBe(4001);
+    expect(state.lastError).toBeNull();
+    expect(mapper.calls.map).toBe(1);
+  });
+
+  it('flips to mode=failed when the mapper throws', async () => {
+    const mapper = makeFakeMapper({ mapShouldThrow: new NatError('mapping_failed', 'router said no') });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper,
+      externalPort: 4001,
+      internalPort: 4001,
+      setTimer: timers.setTimer,
+      clearTimer: timers.clearTimer,
+    });
+
+    await svc.start();
+    expect(svc.getState().mode).toBe('failed');
+    expect(svc.getState().lastError).toContain('router said no');
+  });
+
+  it('unmaps and stops the mapper on stop()', async () => {
+    const mapper = makeFakeMapper();
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper,
+      externalPort: 4001,
+      internalPort: 4001,
+      setTimer: timers.setTimer,
+      clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    await svc.stop();
+    expect(mapper.calls.unmap).toBeGreaterThanOrEqual(1);
+    expect(mapper.calls.stop).toBeGreaterThanOrEqual(1);
+    expect(svc.getState().mode).toBe('disabled');
+  });
+
+  it('stop() is idempotent', async () => {
+    const mapper = makeFakeMapper();
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    await svc.stop();
+    await svc.stop();
+    expect(mapper.calls.unmap).toBe(1);
+  });
+
+  it('refresh() re-maps when verify fails', async () => {
+    const mapper = makeFakeMapper({ verifyResult: false });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    expect(mapper.calls.map).toBe(1);
+
+    await svc.refresh();
+    // verify=false → re-map
+    expect(mapper.calls.map).toBe(2);
+  });
+
+  it('refresh() re-issues the mapping when verify succeeds (extends lease)', async () => {
+    const mapper = makeFakeMapper({ verifyResult: true });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    expect(mapper.calls.map).toBe(1);
+    await svc.refresh();
+    expect(mapper.calls.map).toBe(2);
+    expect(mapper.calls.verify).toBe(1);
+  });
+
+  it('schedules a refresh timer', async () => {
+    const mapper = makeFakeMapper();
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    expect(timers.pending).toBe(1);
+
+    // Fire the timer — should re-arm after the inner refresh resolves.
+    timers.fire();
+    // Wait for the async refresh chain to complete.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(timers.pending).toBe(1);
+  });
+});

package/src/nat/__tests__/reachability.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { evaluateReachability } from '../reachability.js';
+
+describe('evaluateReachability', () => {
+  it('returns cgnat when cgnatDetected is true (overrides portMode)', () => {
+    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: true })).toBe('cgnat');
+    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: true })).toBe('cgnat');
+  });
+
+  it('returns reachable for auto-upnp / auto-natpmp', () => {
+    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: false })).toBe('reachable');
+    expect(evaluateReachability({ portMode: 'auto-natpmp', cgnatDetected: false })).toBe('reachable');
+  });
+
+  it('returns unreachable when port mapping failed', () => {
+    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: false })).toBe('unreachable');
+  });
+
+  it('returns unknown for manual / disabled', () => {
+    expect(evaluateReachability({ portMode: 'manual', cgnatDetected: false })).toBe('unknown');
+    expect(evaluateReachability({ portMode: 'disabled', cgnatDetected: false })).toBe('unknown');
+  });
+});

package/src/nat/__tests__/secrets.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, statSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KeytarSecretsStore } from '../secrets/keytar-store.js';
+import { FileSecretsStore } from '../secrets/file-store.js';
+import { ddnsAccount, type KeytarLike } from '../secrets/index.js';
+import { NatError } from '../types.js';
+
+function makeFakeKeytar(): {
+  keytar: KeytarLike;
+  store: Map<string, string>;
+  injectThrow: (op: keyof KeytarLike, err: Error) => void;
+  clearThrow: () => void;
+} {
+  const store = new Map<string, string>();
+  const throws: Partial<Record<keyof KeytarLike, Error>> = {};
+  const key = (svc: string, acct: string) => `${svc}::${acct}`;
+
+  const keytar: KeytarLike = {
+    async setPassword(svc, acct, password) {
+      if (throws.setPassword) throw throws.setPassword;
+      store.set(key(svc, acct), password);
+    },
+    async getPassword(svc, acct) {
+      if (throws.getPassword) throw throws.getPassword;
+      return store.get(key(svc, acct)) ?? null;
+    },
+    async deletePassword(svc, acct) {
+      if (throws.deletePassword) throw throws.deletePassword;
+      return store.delete(key(svc, acct));
+    },
+    async findCredentials(svc) {
+      if (throws.findCredentials) throw throws.findCredentials;
+      const out: Array<{ account: string; password: string }> = [];
+      for (const [k, v] of store) {
+        const [s, a] = k.split('::');
+        if (s === svc) out.push({ account: a!, password: v });
+      }
+      return out;
+    },
+  };
+  return {
+    keytar,
+    store,
+    injectThrow: (op, err) => { throws[op] = err; },
+    clearThrow: () => { for (const k of Object.keys(throws)) delete throws[k as keyof KeytarLike]; },
+  };
+}
+
+describe('ddnsAccount()', () => {
+  it('formats provider + field into a stable key', () => {
+    expect(ddnsAccount('duckdns', 'token')).toBe('ddns:duckdns:token');
+  });
+
+  it('rejects empty inputs', () => {
+    expect(() => ddnsAccount('', 'token')).toThrow(NatError);
+    expect(() => ddnsAccount('duckdns', '')).toThrow(NatError);
+  });
+});
+
+describe('KeytarSecretsStore', () => {
+  it('round-trips a credential', async () => {
+    const { keytar } = makeFakeKeytar();
+    const s = new KeytarSecretsStore('test-svc', keytar);
+    await s.set('a', 'v1');
+    expect(await s.get('a')).toBe('v1');
+    expect(await s.delete('a')).toBe(true);
+    expect(await s.get('a')).toBeNull();
+  });
+
+  it('lists accounts', async () => {
+    const { keytar } = makeFakeKeytar();
+    const s = new KeytarSecretsStore('svc-1', keytar);
+    await s.set('one', 'v');
+    await s.set('two', 'v');
+    expect((await s.list()).sort()).toEqual(['one', 'two']);
+  });
+
+  it('wraps keytar errors as NatError(secrets_unavailable)', async () => {
+    const fake = makeFakeKeytar();
+    const s = new KeytarSecretsStore('svc', fake.keytar);
+    fake.injectThrow('setPassword', new Error('dbus error'));
+    await expect(s.set('a', 'b')).rejects.toMatchObject({ code: 'secrets_unavailable' });
+
+    fake.clearThrow();
+    fake.injectThrow('getPassword', new Error('boom'));
+    await expect(s.get('a')).rejects.toMatchObject({ code: 'secrets_unavailable' });
+
+    fake.clearThrow();
+    fake.injectThrow('deletePassword', new Error('boom'));
+    await expect(s.delete('a')).rejects.toMatchObject({ code: 'secrets_unavailable' });
+
+    fake.clearThrow();
+    fake.injectThrow('findCredentials', new Error('boom'));
+    await expect(s.list()).rejects.toMatchObject({ code: 'secrets_unavailable' });
+  });
+});
+
+describe('FileSecretsStore', () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-secrets-'));
+  });
+  afterEach(() => {
+    try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it('round-trips credentials through disk', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('ddns:duckdns:token', 'TOKEN');
+    expect(await s.get('ddns:duckdns:token')).toBe('TOKEN');
+
+    const reread = new FileSecretsStore(tmpRoot);
+    expect(await reread.get('ddns:duckdns:token')).toBe('TOKEN');
+  });
+
+  it('lists and deletes', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    await s.set('b', '2');
+    expect((await s.list()).sort()).toEqual(['a', 'b']);
+    expect(await s.delete('a')).toBe(true);
+    expect(await s.delete('a')).toBe(false);
+    expect(await s.list()).toEqual(['b']);
+  });
+
+  it('returns null for unknown account', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    expect(await s.get('nope')).toBeNull();
+  });
+
+  it('throws on malformed file rather than silently wiping', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    writeFileSync(s.filePath(), 'not json', 'utf8');
+    await expect(s.list()).rejects.toBeInstanceOf(NatError);
+  });
+
+  it.runIf(process.platform !== 'win32')('writes secrets file with mode 0600', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    expect(existsSync(s.filePath())).toBe(true);
+    const mode = statSync(s.filePath()).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+
+  it('persists version field', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    const raw = JSON.parse(readFileSync(s.filePath(), 'utf8'));
+    expect(raw.version).toBe(1);
+  });
+});

package/src/nat/address-resolver.ts

@@ -0,0 +1,51 @@
+/**
+ * Build the multiaddrs that should be embedded in invites.
+ *
+ * Inputs are the host's currently-best understanding of its dialable surface:
+ *   - DDNS hostname (`/dns4/<hostname>/...`) when configured AND reachable.
+ *   - Raw external IP (`/ip4/<ip>/...`) when no DDNS but reachable.
+ *   - Whatever libp2p reports otherwise — including any `/p2p-circuit/`
+ *     addresses, once relay-client wiring lands (see follow-up tickets).
+ *
+ * This is intentionally a pure function so it's trivial to unit-test, and so
+ * the NatService can be the only place that knows about settings → multiaddrs.
+ */
+export interface BuildInviteAddressesInput {
+  peerId: string;
+  externalPort: number;
+  ddnsHostname: string | null;
+  externalIp: string | null;
+  reachable: boolean;
+  /** Multiaddrs reported by the underlying libp2p node. */
+  libp2pAddrs: string[];
+}
+
+export function buildInviteAddresses(input: BuildInviteAddressesInput): string[] {
+  const suffix = `/p2p/${input.peerId}`;
+  // DNS path-of-truth: stable across IP changes.
+  if (input.reachable && input.ddnsHostname) {
+    return [`/dns4/${input.ddnsHostname}/tcp/${input.externalPort}${suffix}`];
+  }
+  // Raw IPv4: works when we know our external IP.
+  if (input.reachable && input.externalIp && isIpv4(input.externalIp)) {
+    return [`/ip4/${input.externalIp}/tcp/${input.externalPort}${suffix}`];
+  }
+  // Fallback: whatever libp2p sees. Strip any addresses that lack the
+  // peer suffix and append it for clarity, but otherwise pass through.
+  return input.libp2pAddrs.map((a) => withPeerSuffix(a, input.peerId));
+}
+
+function withPeerSuffix(addr: string, peerId: string): string {
+  if (addr.includes(`/p2p/${peerId}`)) return addr;
+  if (addr.includes('/p2p/')) return addr;  // already has *some* peer
+  return `${addr}/p2p/${peerId}`;
+}
+
+function isIpv4(s: string): boolean {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
+  if (!m) return false;
+  return m.slice(1).every((octet) => {
+    const n = Number(octet);
+    return n >= 0 && n <= 255;
+  });
+}

package/src/nat/ddns/duckdns.ts

@@ -0,0 +1,76 @@
+import debug from 'debug';
+
+import { NatError } from '../types.js';
+import type { DdnsProvider, DdnsProviderDeps } from './index.js';
+
+const log = debug('cadre:host:nat-ddns:duckdns');
+
+/**
+ * DuckDNS provider.
+ *
+ * Update API: HTTPS GET
+ *   https://www.duckdns.org/update?domains=<subdomain>&token=<token>&ip=<ip>
+ * Response is plain text — `OK` on success, `KO` on failure.
+ *
+ * `hostname` may be supplied as the bare subdomain (`foo`) or the FQDN
+ * (`foo.duckdns.org`); we strip the suffix.
+ */
+export const duckDnsProvider: DdnsProvider = {
+  id: 'duckdns',
+  displayName: 'DuckDNS',
+  configFields: [
+    { key: 'token', label: 'DuckDNS token', secret: true },
+  ],
+  async update(
+    config: Record<string, string>,
+    hostname: string,
+    ip: string,
+    deps: DdnsProviderDeps,
+  ): Promise<void> {
+    const token = config['token'];
+    if (!token) {
+      throw new NatError('ddns_credentials_missing', 'DuckDNS requires a `token` config value');
+    }
+    const subdomain = stripSuffix(hostname);
+    if (!subdomain) {
+      throw new NatError('invalid_config', `DuckDNS hostname must be a valid subdomain (got: "${hostname}")`);
+    }
+
+    const url = `https://www.duckdns.org/update?domains=${encodeURIComponent(subdomain)}&token=${encodeURIComponent(token)}&ip=${encodeURIComponent(ip)}`;
+    log('DuckDNS update %s → %s', subdomain, ip);
+
+    let res: Response;
+    try {
+      res = await deps.fetch(url);
+    } catch (err) {
+      throw new NatError(
+        'ddns_update_failed',
+        `DuckDNS request failed: ${(err as Error).message}`,
+      );
+    }
+    if (!res.ok) {
+      throw new NatError(
+        'ddns_update_failed',
+        `DuckDNS HTTP ${res.status}: ${res.statusText}`,
+      );
+    }
+    const text = (await res.text()).trim();
+    if (text !== 'OK') {
+      throw new NatError(
+        'ddns_update_failed',
+        `DuckDNS returned "${text || '(empty)'}" (expected "OK")`,
+      );
+    }
+  },
+};
+
+const SUFFIX = '.duckdns.org';
+
+function stripSuffix(hostname: string): string {
+  const trimmed = hostname.trim().toLowerCase();
+  if (trimmed.length === 0) return '';
+  if (trimmed.endsWith(SUFFIX)) {
+    return trimmed.slice(0, -SUFFIX.length);
+  }
+  return trimmed;
+}

package/src/nat/ddns/index.ts

@@ -0,0 +1,55 @@
+import { NatError, type DdnsConfigField } from '../types.js';
+import { duckDnsProvider } from './duckdns.js';
+
+/** Per-provider runtime dependencies (fetch override for tests). */
+export interface DdnsProviderDeps {
+  fetch: typeof fetch;
+}
+
+/**
+ * DDNS provider interface. Each provider knows:
+ *   - Its display name + the fields needed to configure it (which fields are
+ *     secrets vs. plain config goes into the SecretsStore / nat.json split).
+ *   - How to push an IP update to the provider's API.
+ *
+ * v1 ships DuckDNS only. New providers drop in by exporting a `DdnsProvider`
+ * and adding an entry to `BUILTIN_PROVIDERS`.
+ */
+export interface DdnsProvider {
+  readonly id: string;
+  readonly displayName: string;
+  readonly configFields: ReadonlyArray<DdnsConfigField>;
+  /** Push `ip` for `hostname`. Throws NatError(ddns_update_failed) on failure. */
+  update(
+    config: Record<string, string>,
+    hostname: string,
+    ip: string,
+    deps: DdnsProviderDeps,
+  ): Promise<void>;
+}
+
+/** Built-in DDNS providers. */
+export const BUILTIN_PROVIDERS: Readonly<Record<string, DdnsProvider>> = {
+  duckdns: duckDnsProvider,
+};
+
+/** Look up a provider by ID, throwing NatError(ddns_provider_unknown) if missing. */
+export function getProvider(providerId: string): DdnsProvider {
+  const p = BUILTIN_PROVIDERS[providerId];
+  if (!p) {
+    throw new NatError(
+      'ddns_provider_unknown',
+      `Unknown DDNS provider: ${providerId}. Built-in: ${Object.keys(BUILTIN_PROVIDERS).join(', ')}`,
+    );
+  }
+  return p;
+}
+
+/** List all built-in providers. */
+export function listProviders(): DdnsProvider[] {
+  return Object.values(BUILTIN_PROVIDERS);
+}
+
+export { duckDnsProvider } from './duckdns.js';
+export { DdnsUpdater } from './updater.js';
+export type { DdnsUpdaterOptions, DdnsUpdateOutcome } from './updater.js';