@serfab/cadre-host 1.12.0 → 1.14.0

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

@@ -1,93 +1,127 @@
-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);
-  });
-});
+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 */ }
+});
+
+function rawFile(): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(tmpRoot, 'nat.json'), 'utf8')) as Record<string, unknown>;
+}
+
+describe('NatStore', () => {
+  it('returns defaults when file is missing', () => {
+    const store = new NatStore(tmpRoot);
+    const s = store.load();
+    expect(s.upnpEnabled).toBe(true);
+    expect(s.forwards).toEqual({});
+    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({ upnpEnabled: false });
+
+    expect(existsSync(join(tmpRoot, 'nat.json'))).toBe(true);
+    expect(existsSync(join(tmpRoot, 'nat.json.tmp'))).toBe(false);
+
+    const reread = new NatStore(tmpRoot);
+    expect(reread.load().upnpEnabled).toBe(false);
+    expect(rawFile().version).toBe(1);
+  });
+
+  it('loads a file written by an older build and drops its single-port fields on save', () => {
+    writeFileSync(join(tmpRoot, 'nat.json'), JSON.stringify({
+      version: 1,
+      externalPort: 4001,
+      internalPort: 4001,
+      upnpEnabled: false,
+      ddns: { providerId: null, hostname: null, externallyManaged: false, intervalMs: 300_000 },
+    }), 'utf8');
+    const store = new NatStore(tmpRoot);
+    const s = store.load();
+    expect(s.upnpEnabled).toBe(false);
+    expect(s.forwards).toEqual({});
+    expect('externalPort' in s).toBe(false);
+
+    store.update({ upnpEnabled: true });
+    const raw = rawFile();
+    expect(raw.externalPort).toBeUndefined();
+    expect(raw.internalPort).toBeUndefined();
+    expect(raw.forwards).toEqual({});
+  });
+
+  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('setForward sets, clears and removes per-port entries', () => {
+    const store = new NatStore(tmpRoot);
+    expect(store.setForward('a', { tcp: 40000, ws: 40001 }).forwards).toEqual({ a: { tcp: 40000, ws: 40001 } });
+    expect(store.setForward('a', { tcp: null }).forwards).toEqual({ a: { ws: 40001 } });
+    expect(store.setForward('a', { ws: 40002 }).forwards).toEqual({ a: { ws: 40002 } });
+    expect(store.setForward('a', { ws: null }).forwards).toEqual({});
+    expect(new NatStore(tmpRoot).load().forwards).toEqual({});
+  });
+
+  it('deleteForward drops one node and leaves the rest', () => {
+    const store = new NatStore(tmpRoot);
+    store.setForward('a', { tcp: 40000 });
+    store.setForward('b', { ws: 40001 });
+    expect(store.deleteForward('a').forwards).toEqual({ b: { ws: 40001 } });
+    expect(store.deleteForward('missing').forwards).toEqual({ b: { ws: 40001 } });
+  });
+
+  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 an out-of-range or non-integer forwarded port', () => {
+    const store = new NatStore(tmpRoot);
+    expect(() => store.setForward('a', { tcp: 0 })).toThrow(NatError);
+    expect(() => store.setForward('a', { ws: 70000 })).toThrow(NatError);
+    expect(() => store.setForward('a', { tcp: 1.5 })).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

@@ -1,191 +1,30 @@
-import { describe, expect, it } 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);
-  });
-});
+import { describe, expect, it } from 'vitest';
+import type { NetworkInterfaceInfo } from 'node:os';
+
+import { pickLanAddress } from '../port-mapper.js';
+
+function v4(address: string, cidr: string, internal = false): NetworkInterfaceInfo {
+  return { address, netmask: '', family: 'IPv4', mac: '00:00:00:00:00:00', internal, cidr };
+}
+
+/**
+ * The address a mapping points at (and a user is told to forward to) must be
+ * the one on the router's own subnet — not a VPN or container interface that
+ * happens to come first.
+ */
+describe('pickLanAddress', () => {
+  it('picks the interface whose subnet contains the router, skipping loopback and other subnets', () => {
+    const interfaces = {
+      lo: [{ address: '127.0.0.1', netmask: '', family: 'IPv4', mac: '', internal: true, cidr: '127.0.0.1/8' } as NetworkInterfaceInfo],
+      docker0: [v4('172.17.0.1', '172.17.0.1/16')],
+      tun0: [v4('10.8.0.2', '10.8.0.2/24')],
+      eth0: [v4('192.168.1.20', '192.168.1.20/24')],
+    };
+    expect(pickLanAddress('192.168.1.1', interfaces)).toBe('192.168.1.20');
+    expect(pickLanAddress('10.8.0.1', interfaces)).toBe('10.8.0.2');
+  });
+
+  it('returns null when no interface shares the router subnet', () => {
+    expect(pickLanAddress('192.168.1.1', { eth0: [v4('10.0.0.5', '10.0.0.5/24')] })).toBeNull();
+  });
+});

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

@@ -1,24 +1,107 @@
 import { describe, expect, it } from 'vitest';
 
-import { evaluateReachability } from '../reachability.js';
+import { evaluateHostReachability, evaluateNodeReachability, type NodeVerdictInput } from '../reachability.js';
+import type { PortRoute } from '../types.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');
+function upnp(internalPort: number): PortRoute {
+  return { internalPort, externalPort: internalPort, source: 'upnp', leaseExpiresAt: null, error: null };
+}
+function manual(internalPort: number): PortRoute {
+  return { internalPort, externalPort: 40000, source: 'manual', leaseExpiresAt: null, error: null };
+}
+function none(internalPort: number, error: string | null = null): PortRoute {
+  return { internalPort, externalPort: null, source: null, leaseExpiresAt: null, error };
+}
+
+const BASE: NodeVerdictInput = {
+  tcp: upnp(10003),
+  ws: upnp(10004),
+  hostKnown: true,
+  cgnatDetected: false,
+  upnpEnabled: true,
+  gatewayFound: true,
+  lanAddress: '192.168.1.20',
+};
+
+describe('evaluateNodeReachability', () => {
+  it('mapped when both ports have UPnP routes', () => {
+    expect(evaluateNodeReachability(BASE)).toEqual({ verdict: 'mapped', reason: null });
+  });
+
+  it('manual when either port is forwarded by hand', () => {
+    expect(evaluateNodeReachability({ ...BASE, ws: manual(10004) }).verdict).toBe('manual');
+  });
+
+  it('a node without a WebSocket port is judged on TCP alone', () => {
+    expect(evaluateNodeReachability({ ...BASE, ws: null }).verdict).toBe('mapped');
+  });
+
+  it('unreachable when the host part is unknown, whatever the routes', () => {
+    const r = evaluateNodeReachability({ ...BASE, hostKnown: false });
+    expect(r.verdict).toBe('unreachable');
+    expect(r.reason).toContain('public address is unknown');
+  });
+
+  it('a refused port names the port, the LAN address and the remedy', () => {
+    const r = evaluateNodeReachability({ ...BASE, ws: none(10004, 'mapping table is full') });
+    expect(r.verdict).toBe('unreachable');
+    expect(r.reason).toBe(
+      'Router refused the WebSocket port 10004 mapping (mapping table is full). ' +
+      'Forward port 10004 to 192.168.1.20 on your router, then tell cadre-host the external port.',
+    );
+  });
+
+  it('two ports failing for one cause are named in one sentence', () => {
+    const r = evaluateNodeReachability({ ...BASE, tcp: none(10003), ws: none(10004), upnpEnabled: false });
+    expect(r.reason).toContain('TCP port 10003 and WebSocket port 10004 are not mapped');
+    expect(r.reason).toContain('forward ports 10003 and 10004 to 192.168.1.20');
+  });
+
+  it('with no gateway the remedy says so and falls back to a generic LAN address', () => {
+    const r = evaluateNodeReachability({ ...BASE, tcp: none(10003), ws: none(10004), gatewayFound: false, lanAddress: null });
+    expect(r.reason).toContain('No UPnP router answered');
+    expect(r.reason).toContain("this machine's LAN address");
+  });
+
+  it('a port not yet attempted reads as pending', () => {
+    expect(evaluateNodeReachability({ ...BASE, tcp: none(10003) }).reason).toContain('not mapped yet');
+  });
+
+  it('under CGNAT a UPnP route is unreachable and a forward will not help; manual routes are fine', () => {
+    const r = evaluateNodeReachability({ ...BASE, cgnatDetected: true });
+    expect(r.verdict).toBe('unreachable');
+    expect(r.reason).toContain('carrier-grade NAT');
+    expect(r.reason).toContain('a relay is needed');
+    const refused = evaluateNodeReachability({ ...BASE, cgnatDetected: true, ws: none(10004, 'mapping table is full') });
+    expect(refused.reason).not.toContain('Forward port');
+    expect(evaluateNodeReachability({ ...BASE, cgnatDetected: true, tcp: manual(10003), ws: manual(10004) }).verdict).toBe('manual');
+  });
+});
+
+describe('evaluateHostReachability', () => {
+  it('unknown with no running nodes', () => {
+    expect(evaluateHostReachability([], false)).toBe('unknown');
+    expect(evaluateHostReachability([{ running: false, verdict: 'unreachable' }], false)).toBe('unknown');
   });
 
-  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('reachable when every running node is mapped or manual', () => {
+    expect(evaluateHostReachability([
+      { running: true, verdict: 'mapped' },
+      { running: true, verdict: 'manual' },
+      { running: false, verdict: 'unreachable' },
+    ], false)).toBe('reachable');
   });
 
-  it('returns unreachable when port mapping failed', () => {
-    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: false })).toBe('unreachable');
+  it('unreachable when any running node is', () => {
+    expect(evaluateHostReachability([
+      { running: true, verdict: 'mapped' },
+      { running: true, verdict: 'unreachable' },
+    ], 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');
+  it('cgnat when detected and no node is reachable through a manual route', () => {
+    expect(evaluateHostReachability([{ running: true, verdict: 'unreachable' }], true)).toBe('cgnat');
+    expect(evaluateHostReachability([], true)).toBe('cgnat');
+    expect(evaluateHostReachability([{ running: true, verdict: 'manual' }], true)).toBe('reachable');
   });
 });