@serfab/cadre-host 1.14.0 → 1.15.0

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

@@ -1,127 +1,130 @@
-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);
-  });
-});
+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.network).toBe('auto');
+    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);
+    // Written before network modes existed: reads as `auto`.
+    expect(s.network).toBe('auto');
+
+    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__/network-mode.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import type { NetworkInterfaceInfo } from 'node:os';
+
+import { effectiveNetworkMode, publicInterfaceAddress } from '../network-mode.js';
+
+/** One IPv4 interface entry, as `os.networkInterfaces()` reports it. */
+function v4(address: string, internal = false): NetworkInterfaceInfo {
+  return { address, netmask: '255.255.255.0', family: 'IPv4', mac: '00:00:00:00:00:00', internal, cidr: `${address}/24` };
+}
+
+describe('publicInterfaceAddress', () => {
+  it('finds a VPS\'s public address among private, Docker and loopback interfaces', () => {
+    expect(publicInterfaceAddress({
+      lo: [v4('127.0.0.1', true)],
+      docker0: [v4('172.17.0.1')],
+      eth1: [v4('10.10.0.5')],
+      eth0: [v4('107.170.255.209')],
+    })).toBe('107.170.255.209');
+  });
+
+  it('is null behind a router: private, carrier-grade and link-local addresses only', () => {
+    expect(publicInterfaceAddress({
+      eno1: [v4('192.168.2.27')],
+      tailscale0: [v4('100.101.102.103')],
+      bk0: [v4('10.9.9.1')],
+      wlan0: [v4('169.254.10.10')],
+    })).toBeNull();
+  });
+});
+
+describe('effectiveNetworkMode', () => {
+  it('auto follows the interfaces; an explicit setting wins', () => {
+    expect(effectiveNetworkMode('auto', '203.0.113.7')).toBe('public');
+    expect(effectiveNetworkMode('auto', null)).toBe('lan');
+    expect(effectiveNetworkMode('lan', '203.0.113.7')).toBe('lan');
+    expect(effectiveNetworkMode('public', null)).toBe('public');
+  });
+});

package/src/nat/index.ts

@@ -1,87 +1,91 @@
-/**
- * NAT / DDNS substrate for cadre-host.
- *
- * See ./nat-service.ts for the top-level orchestrator and `docs/cadre-host.md`
- * for integration notes (the long-running process owner is `cadre-host start`).
- */
-
-export {
-  NatService,
-  createNatHandlers,
-  NAT_UNMAP_GRACE_MS,
-  NAT_RECONCILE_INTERVAL_MS,
-  NAT_IP_REDETECT_INTERVAL_MS,
-} from './nat-service.js';
-export type { NatServiceOptions, NatNodeSource, NatChangeListener } from './nat-service.js';
-export { NAT_ADDRESS_RESTART_MIN_INTERVAL_MS } from './address-watch.js';
-export type { NodeAddressesStaleListener } from './address-watch.js';
-export { NatStore } from './nat-store.js';
-export {
-  NatError,
-} from './types.js';
-export type {
-  NatStatusSnapshot,
-  NatGatewayStatus,
-  NatDdnsStatus,
-  NatSettingsFile,
-  NatDdnsSettings,
-  NatHandlers,
-  NatErrorCode,
-  DirectReachability,
-  NodeReachability,
-  NodeVerdict,
-  PortKind,
-  PortRoute,
-  PortRouteSource,
-  ManualForward,
-  ManualForwardPatch,
-  DdnsProviderInfo,
-  DdnsConfigField,
-} from './types.js';
-export {
-  ExternalIpDetector,
-  isPlausibleIp,
-} from './external-ip.js';
-export type {
-  ExternalIpResult,
-  RouterIpProbe,
-  ExternalIpDetectorOptions,
-} from './external-ip.js';
-export {
-  UpnpPortMapper,
-  pickLanAddress,
-  DEFAULT_LEASE_TTL_MS,
-  DEFAULT_REFRESH_MS,
-  GATEWAY_DISCOVERY_TIMEOUT_MS,
-} from './port-mapper.js';
-export type {
-  PortMapper,
-  GatewayInfo,
-  PortMapRequest,
-  PortMapResult,
-} from './port-mapper.js';
-export { evaluateNodeReachability, evaluateHostReachability } from './reachability.js';
-export type { NodeVerdictInput, NodeVerdictResult } from './reachability.js';
-export { buildPublicAddresses, isPublicIpv4 } from './address-resolver.js';
-export type { PublicAddressInput } from './address-resolver.js';
-export {
-  BUILTIN_PROVIDERS,
-  getProvider,
-  listProviders,
-  duckDnsProvider,
-  DdnsUpdater,
-} from './ddns/index.js';
-export type {
-  DdnsProvider,
-  DdnsProviderDeps,
-  DdnsUpdaterOptions,
-  DdnsUpdateOutcome,
-} from './ddns/index.js';
-export {
-  KeytarSecretsStore,
-  FileSecretsStore,
-  createSecretsStore,
-  ddnsAccount,
-  KEYTAR_SERVICE,
-} from './secrets/index.js';
-export type { SecretsStore, KeytarLike } from './secrets/index.js';
+/**
+ * NAT / DDNS substrate for cadre-host.
+ *
+ * See ./nat-service.ts for the top-level orchestrator and `docs/cadre-host.md`
+ * for integration notes (the long-running process owner is `cadre-host start`).
+ */
+
+export {
+  NatService,
+  createNatHandlers,
+  NAT_UNMAP_GRACE_MS,
+  NAT_RECONCILE_INTERVAL_MS,
+  NAT_IP_REDETECT_INTERVAL_MS,
+} from './nat-service.js';
+export type { NatServiceOptions, NatNodeSource, NatChangeListener } from './nat-service.js';
+export { NAT_ADDRESS_RESTART_MIN_INTERVAL_MS } from './address-watch.js';
+export type { NodeAddressesStaleListener } from './address-watch.js';
+export { NatStore } from './nat-store.js';
+export {
+  NatError,
+} from './types.js';
+export type {
+  NatStatusSnapshot,
+  NatGatewayStatus,
+  NatDdnsStatus,
+  NatNetworkStatus,
+  NetworkMode,
+  NetworkSetting,
+  NatSettingsFile,
+  NatDdnsSettings,
+  NatHandlers,
+  NatErrorCode,
+  DirectReachability,
+  NodeReachability,
+  NodeVerdict,
+  PortKind,
+  PortRoute,
+  PortRouteSource,
+  ManualForward,
+  ManualForwardPatch,
+  DdnsProviderInfo,
+  DdnsConfigField,
+} from './types.js';
+export {
+  ExternalIpDetector,
+  isPlausibleIp,
+} from './external-ip.js';
+export type {
+  ExternalIpResult,
+  RouterIpProbe,
+  ExternalIpDetectorOptions,
+} from './external-ip.js';
+export {
+  UpnpPortMapper,
+  pickLanAddress,
+  DEFAULT_LEASE_TTL_MS,
+  DEFAULT_REFRESH_MS,
+  GATEWAY_DISCOVERY_TIMEOUT_MS,
+} from './port-mapper.js';
+export type {
+  PortMapper,
+  GatewayInfo,
+  PortMapRequest,
+  PortMapResult,
+} from './port-mapper.js';
+export { evaluateNodeReachability, evaluateHostReachability } from './reachability.js';
+export type { NodeVerdictInput, NodeVerdictResult } from './reachability.js';
+export { buildPublicAddresses, isPublicIpv4 } from './address-resolver.js';
+export { publicInterfaceAddress, effectiveNetworkMode } from './network-mode.js';
+export type { PublicAddressInput } from './address-resolver.js';
+export {
+  BUILTIN_PROVIDERS,
+  getProvider,
+  listProviders,
+  duckDnsProvider,
+  DdnsUpdater,
+} from './ddns/index.js';
+export type {
+  DdnsProvider,
+  DdnsProviderDeps,
+  DdnsUpdaterOptions,
+  DdnsUpdateOutcome,
+} from './ddns/index.js';
+export {
+  KeytarSecretsStore,
+  FileSecretsStore,
+  createSecretsStore,
+  ddnsAccount,
+  KEYTAR_SERVICE,
+} from './secrets/index.js';
+export type { SecretsStore, KeytarLike } from './secrets/index.js';