@serfab/cadre-host 0.7.1

package/src/nat/port-mapper.ts

@@ -0,0 +1,329 @@
+import debug from 'debug';
+
+import { NatError, type PortForwardMode } from './types.js';
+
+const log = debug('cadre:host:nat-port-mapper');
+
+/** Default lease TTL: 1 hour. The router must keep our mapping at least this long. */
+export const DEFAULT_LEASE_TTL_MS = 60 * 60 * 1000;
+
+/** Default refresh cadence: half the TTL, so two refreshes per lease. */
+export const DEFAULT_REFRESH_MS = 30 * 60 * 1000;
+
+/** Result of a successful map(). */
+export interface PortMappingResult {
+  mode: 'auto-upnp' | 'auto-natpmp';
+  externalIp: string | null;
+  externalPort: number;
+  internalPort: number;
+  protocol: 'tcp' | 'udp';
+  leaseExpiresAt: Date;
+}
+
+export interface PortMapOptions {
+  externalPort: number;
+  internalPort: number;
+  protocol?: 'tcp' | 'udp';
+  /** Lease TTL in milliseconds. Defaults to DEFAULT_LEASE_TTL_MS. */
+  ttlMs?: number;
+}
+
+/**
+ * Wrapper around the underlying UPnP/NAT-PMP client. Abstract so tests can
+ * stub the network behavior without spinning up a real router.
+ */
+export interface PortMapper {
+  /** Attempt to install a port mapping. Throws NatError(mapping_failed) on failure. */
+  map(opts: PortMapOptions): Promise<PortMappingResult>;
+  /** Re-query the router; returns true if the mapping is still present. */
+  verify(externalPort: number, protocol?: 'tcp' | 'udp'): Promise<boolean>;
+  /** Query the router's WAN/external IP, if exposed. */
+  externalIp(): Promise<string | null>;
+  /** Remove a mapping installed by this mapper. */
+  unmap(externalPort: number, protocol?: 'tcp' | 'udp'): Promise<void>;
+  /** Release client resources (timers, sockets). Idempotent. */
+  stop(): Promise<void>;
+}
+
+/** Constructor for the default mapper. Loads `@achingbrain/nat-port-mapper` dynamically. */
+export type PortMapperFactory = () => Promise<PortMapper>;
+
+interface NatPortMapperClient {
+  externalIp(): Promise<string>;
+  map(opts: Record<string, unknown>): Promise<unknown>;
+  unmap(opts: Record<string, unknown>): Promise<void>;
+  stop(): Promise<void>;
+}
+
+interface NatPortMapperModule {
+  upnpNat(opts?: Record<string, unknown>): Promise<NatPortMapperClient>;
+}
+
+/**
+ * Default factory: loads @achingbrain/nat-port-mapper. Wrapped in dynamic
+ * import so a missing dep at install time doesn't crash the package.
+ */
+export async function createDefaultPortMapper(opts: {
+  description?: string;
+  ttlMs?: number;
+} = {}): Promise<PortMapper> {
+  let mod: NatPortMapperModule;
+  try {
+    mod = (await import('@achingbrain/nat-port-mapper' as string)) as NatPortMapperModule;
+  } catch (err) {
+    throw new NatError(
+      'mapping_failed',
+      `@achingbrain/nat-port-mapper is not installed: ${(err as Error).message}`,
+    );
+  }
+
+  let client: NatPortMapperClient;
+  try {
+    client = await mod.upnpNat({
+      description: opts.description ?? 'sereus-cadre-host',
+      ttl: Math.round((opts.ttlMs ?? DEFAULT_LEASE_TTL_MS) / 1000),
+    });
+  } catch (err) {
+    throw new NatError(
+      'mapping_failed',
+      `upnpNat() failed: ${(err as Error).message}`,
+    );
+  }
+
+  return new NatPortMapperAdapter(client, opts.ttlMs ?? DEFAULT_LEASE_TTL_MS);
+}
+
+class NatPortMapperAdapter implements PortMapper {
+  constructor(
+    private readonly client: NatPortMapperClient,
+    private readonly defaultTtlMs: number,
+  ) {}
+
+  async map(opts: PortMapOptions): Promise<PortMappingResult> {
+    const ttlMs = opts.ttlMs ?? this.defaultTtlMs;
+    const protocol = opts.protocol ?? 'tcp';
+    let externalIp: string | null = null;
+    try {
+      externalIp = await this.client.externalIp();
+    } catch (err) {
+      log('externalIp() failed: %s', (err as Error).message);
+    }
+    try {
+      await this.client.map({
+        localPort: opts.internalPort,
+        externalPort: opts.externalPort,
+        protocol,
+        ttl: Math.round(ttlMs / 1000),
+      });
+    } catch (err) {
+      throw new NatError(
+        'mapping_failed',
+        `router refused mapping for port ${opts.externalPort}: ${(err as Error).message}`,
+      );
+    }
+    return {
+      mode: 'auto-upnp',
+      externalIp,
+      externalPort: opts.externalPort,
+      internalPort: opts.internalPort,
+      protocol,
+      leaseExpiresAt: new Date(Date.now() + ttlMs),
+    };
+  }
+
+  async verify(externalPort: number, protocol: 'tcp' | 'udp' = 'tcp'): Promise<boolean> {
+    void externalPort;
+    void protocol;
+    // The current library doesn't expose an introspection API. Treat a
+    // working externalIp() as a proxy for "router still reachable" — refresh
+    // failures will surface via re-running map().
+    try {
+      await this.client.externalIp();
+      return true;
+    } catch (err) {
+      log('verify() failed: %s', (err as Error).message);
+      return false;
+    }
+  }
+
+  async externalIp(): Promise<string | null> {
+    try {
+      return await this.client.externalIp();
+    } catch (err) {
+      log('externalIp() failed: %s', (err as Error).message);
+      return null;
+    }
+  }
+
+  async unmap(externalPort: number, protocol: 'tcp' | 'udp' = 'tcp'): Promise<void> {
+    try {
+      await this.client.unmap({ externalPort, protocol });
+    } catch (err) {
+      log('unmap(%d) failed: %s', externalPort, (err as Error).message);
+    }
+  }
+
+  async stop(): Promise<void> {
+    try {
+      await this.client.stop();
+    } catch (err) {
+      log('stop() failed: %s', (err as Error).message);
+    }
+  }
+}
+
+/** Public-facing port-mapper service: wraps a PortMapper with refresh + state. */
+export interface PortMapperServiceOptions {
+  mapper: PortMapper;
+  externalPort: number;
+  internalPort: number;
+  protocol?: 'tcp' | 'udp';
+  ttlMs?: number;
+  refreshMs?: number;
+  /** Clock override for tests. */
+  now?: () => Date;
+  /** Timer overrides for tests (must return a handle usable by `clear`). */
+  setTimer?: (fn: () => void, ms: number) => NodeJS.Timeout;
+  clearTimer?: (h: NodeJS.Timeout) => void;
+}
+
+/** State snapshot returned by `PortMapperService.getStatus()`. */
+export interface PortMapperState {
+  mode: PortForwardMode;
+  externalPort: number;
+  internalPort: number;
+  routerExternalIp: string | null;
+  leaseExpiresAt: Date | null;
+  lastError: string | null;
+}
+
+/**
+ * Long-running orchestrator over a PortMapper. Owns the refresh timer and
+ * surfaces the latest state for the NatService snapshot.
+ */
+export class PortMapperService {
+  private readonly mapper: PortMapper;
+  private readonly externalPort: number;
+  private readonly internalPort: number;
+  private readonly protocol: 'tcp' | 'udp';
+  private readonly ttlMs: number;
+  private readonly refreshMs: number;
+  private readonly nowFn: () => Date;
+  private readonly setTimer: (fn: () => void, ms: number) => NodeJS.Timeout;
+  private readonly clearTimer: (h: NodeJS.Timeout) => void;
+
+  private state: PortMapperState;
+  private refreshHandle: NodeJS.Timeout | null = null;
+  private started = false;
+
+  constructor(opts: PortMapperServiceOptions) {
+    this.mapper = opts.mapper;
+    this.externalPort = opts.externalPort;
+    this.internalPort = opts.internalPort;
+    this.protocol = opts.protocol ?? 'tcp';
+    this.ttlMs = opts.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+    this.refreshMs = opts.refreshMs ?? DEFAULT_REFRESH_MS;
+    this.nowFn = opts.now ?? (() => new Date());
+    this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    this.clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+
+    this.state = {
+      mode: 'disabled',
+      externalPort: this.externalPort,
+      internalPort: this.internalPort,
+      routerExternalIp: null,
+      leaseExpiresAt: null,
+      lastError: null,
+    };
+  }
+
+  getState(): PortMapperState {
+    return { ...this.state };
+  }
+
+  /** Install the mapping and schedule periodic refresh. */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    await this.installMapping();
+    this.scheduleRefresh();
+  }
+
+  /** Release the mapping and clear timers. Idempotent. */
+  async stop(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+    if (this.refreshHandle) {
+      this.clearTimer(this.refreshHandle);
+      this.refreshHandle = null;
+    }
+    try {
+      await this.mapper.unmap(this.externalPort, this.protocol);
+    } catch (err) {
+      log('unmap during stop failed: %s', (err as Error).message);
+    }
+    try {
+      await this.mapper.stop();
+    } catch (err) {
+      log('mapper.stop() failed: %s', (err as Error).message);
+    }
+    this.state = {
+      ...this.state,
+      mode: 'disabled',
+      routerExternalIp: null,
+      leaseExpiresAt: null,
+    };
+  }
+
+  /** Force an immediate verify+refresh cycle (used by testReachability). */
+  async refresh(): Promise<PortMapperState> {
+    if (!this.started) return this.getState();
+    const ok = await this.mapper.verify(this.externalPort, this.protocol).catch(() => false);
+    if (!ok) {
+      log('verify() returned false; re-mapping');
+      await this.installMapping();
+      return this.getState();
+    }
+    // Refresh: re-issue the mapping to extend the lease.
+    await this.installMapping();
+    return this.getState();
+  }
+
+  private scheduleRefresh(): void {
+    if (this.refreshHandle) this.clearTimer(this.refreshHandle);
+    this.refreshHandle = this.setTimer(() => {
+      void this.refresh().catch((err) => log('refresh timer error: %s', (err as Error).message));
+      // Re-arm after the call to avoid drift.
+      this.scheduleRefresh();
+    }, this.refreshMs);
+  }
+
+  private async installMapping(): Promise<void> {
+    try {
+      const r = await this.mapper.map({
+        externalPort: this.externalPort,
+        internalPort: this.internalPort,
+        protocol: this.protocol,
+        ttlMs: this.ttlMs,
+      });
+      this.state = {
+        mode: r.mode,
+        externalPort: r.externalPort,
+        internalPort: r.internalPort,
+        routerExternalIp: r.externalIp,
+        leaseExpiresAt: r.leaseExpiresAt,
+        lastError: null,
+      };
+      log('mapped port %d (mode=%s, externalIp=%s)', r.externalPort, r.mode, r.externalIp ?? '?');
+    } catch (err) {
+      const message = (err as Error).message;
+      this.state = {
+        ...this.state,
+        mode: 'failed',
+        leaseExpiresAt: null,
+        lastError: message,
+      };
+      log('mapping failed: %s', message);
+    }
+  }
+}

package/src/nat/reachability.ts

@@ -0,0 +1,34 @@
+import type { DirectReachability, PortForwardMode } from './types.js';
+
+export interface ReachabilityInput {
+  portMode: PortForwardMode;
+  cgnatDetected: boolean;
+}
+
+/**
+ * v1 reachability heuristic.
+ *
+ * Returns:
+ *   - 'cgnat' when CGNAT was detected (highest signal — UPnP succeeded but our
+ *     external IP isn't actually reachable from the open internet).
+ *   - 'unreachable' when port mapping failed.
+ *   - 'reachable' when an auto mapping succeeded.
+ *   - 'unknown' otherwise (manual config, disabled UPnP, etc).
+ *
+ * A future ticket will replace this with libp2p AutoNAT or a sereus-owned
+ * dial-back probe (see the follow-up section of `6.3-cadre-host-nat`).
+ */
+export function evaluateReachability(input: ReachabilityInput): DirectReachability {
+  if (input.cgnatDetected) return 'cgnat';
+  switch (input.portMode) {
+    case 'auto-upnp':
+    case 'auto-natpmp':
+      return 'reachable';
+    case 'failed':
+      return 'unreachable';
+    case 'manual':
+    case 'disabled':
+    default:
+      return 'unknown';
+  }
+}

package/src/nat/secrets/file-store.ts

@@ -0,0 +1,130 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+
+import { NatError } from '../types.js';
+import type { SecretsStore } from './index.js';
+
+const log = debug('cadre:host:nat-secrets:file');
+
+const FILE_VERSION = 1;
+
+interface FileShape {
+  version: 1;
+  /** Account → secret value. */
+  entries: Record<string, string>;
+}
+
+/**
+ * Filesystem fallback for `SecretsStore`. Writes to `<rootDir>/nat-secrets.json`
+ * with mode 0o600.
+ *
+ * This is NOT a substitute for the OS keychain — the file is plain JSON, only
+ * protected by POSIX permissions. We use it only when keytar is unavailable
+ * and the caller has been warned (see `createSecretsStore`).
+ *
+ * Windows: chmod is a no-op (mode bits don't apply), so the file is readable
+ * by any user on the same machine. This is documented.
+ */
+export class FileSecretsStore implements SecretsStore {
+  private readonly path: string;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, 'nat-secrets.json');
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+
+  async set(account: string, value: string): Promise<void> {
+    const data = this.load();
+    data.entries[account] = value;
+    this.save(data);
+  }
+
+  async get(account: string): Promise<string | null> {
+    const data = this.load();
+    return Object.prototype.hasOwnProperty.call(data.entries, account)
+      ? data.entries[account]!
+      : null;
+  }
+
+  async delete(account: string): Promise<boolean> {
+    const data = this.load();
+    if (!Object.prototype.hasOwnProperty.call(data.entries, account)) return false;
+    delete data.entries[account];
+    this.save(data);
+    return true;
+  }
+
+  async list(): Promise<string[]> {
+    return Object.keys(this.load().entries);
+  }
+
+  private load(): FileShape {
+    if (!existsSync(this.path)) {
+      return { version: FILE_VERSION, entries: {} };
+    }
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, 'utf8');
+    } catch (err) {
+      throw new NatError(
+        'storage_error',
+        `failed to read nat-secrets file at ${this.path}: ${(err as Error).message}`,
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new NatError(
+        'storage_error',
+        `nat-secrets file at ${this.path} is not valid JSON: ${(err as Error).message}`,
+      );
+    }
+    if (!isFileShape(parsed)) {
+      throw new NatError(
+        'storage_error',
+        `nat-secrets file at ${this.path} has unexpected shape`,
+      );
+    }
+    return parsed;
+  }
+
+  private save(data: FileShape): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const payload = JSON.stringify({ ...data, version: FILE_VERSION }, null, 2);
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, this.path);
+    // chmod again after rename — some platforms reset perms on rename.
+    if (process.platform !== 'win32') {
+      try {
+        chmodSync(this.path, 0o600);
+      } catch (err) {
+        log('chmod 0600 on %s failed: %s', this.path, (err as Error).message);
+      }
+    }
+  }
+}
+
+function isFileShape(v: unknown): v is FileShape {
+  if (!v || typeof v !== 'object') return false;
+  const obj = v as Record<string, unknown>;
+  if (obj.version !== FILE_VERSION) return false;
+  if (!obj.entries || typeof obj.entries !== 'object') return false;
+  for (const val of Object.values(obj.entries as Record<string, unknown>)) {
+    if (typeof val !== 'string') return false;
+  }
+  return true;
+}

package/src/nat/secrets/index.ts

@@ -0,0 +1,82 @@
+import debug from 'debug';
+
+import { NatError } from '../types.js';
+import { KeytarSecretsStore } from './keytar-store.js';
+import { FileSecretsStore } from './file-store.js';
+
+const log = debug('cadre:host:nat-secrets');
+
+/** Service name used as the keytar collection. */
+export const KEYTAR_SERVICE = 'sereus-cadre-host';
+
+/**
+ * Abstract credential store. Keys are opaque to the store
+ * (e.g. "ddns:duckdns:token").
+ */
+export interface SecretsStore {
+  set(account: string, value: string): Promise<void>;
+  get(account: string): Promise<string | null>;
+  delete(account: string): Promise<boolean>;
+  list(): Promise<string[]>;
+}
+
+export { KeytarSecretsStore, FileSecretsStore };
+
+/**
+ * Try the OS keychain (keytar) first; fall back to a 0600 JSON file in the
+ * cadre-host rootDir. The fallback path is documented in `docs/cadre-host.md`.
+ *
+ * `keytar` is loaded via dynamic import inside a try/catch so a missing native
+ * dependency never crashes package import. The same applies to runtime errors
+ * (some Linux desktops have keytar installed but no DBus secret service).
+ */
+export async function createSecretsStore(rootDir: string): Promise<SecretsStore> {
+  // First, try to load keytar.
+  let keytarMod: unknown;
+  try {
+    keytarMod = await import('keytar');
+  } catch (err) {
+    log('keytar unavailable (%s); using file fallback', (err as Error).message);
+    return makeFileFallback(rootDir, `keytar not installed: ${(err as Error).message}`);
+  }
+
+  // Probe with a sentinel write — some installs load but throw at runtime.
+  const ks = new KeytarSecretsStore(KEYTAR_SERVICE, keytarMod as KeytarLike);
+  const probeAccount = '__cadre_host_probe__';
+  try {
+    await ks.set(probeAccount, '1');
+    await ks.delete(probeAccount);
+    log('using keytar for DDNS credentials (service=%s)', KEYTAR_SERVICE);
+    return ks;
+  } catch (err) {
+    log('keytar probe failed (%s); using file fallback', (err as Error).message);
+    return makeFileFallback(rootDir, `keytar runtime error: ${(err as Error).message}`);
+  }
+}
+
+function makeFileFallback(rootDir: string, reason: string): SecretsStore {
+  const store = new FileSecretsStore(rootDir);
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[cadre-host] DDNS credentials will be stored UNENCRYPTED at ` +
+    `${store.filePath()} (${reason}). Install keytar's native dependencies ` +
+    `for OS keychain protection.`,
+  );
+  return store;
+}
+
+/** Subset of keytar's surface that KeytarSecretsStore uses. */
+export interface KeytarLike {
+  setPassword(service: string, account: string, password: string): Promise<void>;
+  getPassword(service: string, account: string): Promise<string | null>;
+  deletePassword(service: string, account: string): Promise<boolean>;
+  findCredentials(service: string): Promise<Array<{ account: string; password: string }>>;
+}
+
+/** Build the keytar account key for a DDNS credential. */
+export function ddnsAccount(providerId: string, fieldKey: string): string {
+  if (!providerId || !fieldKey) {
+    throw new NatError('invalid_config', 'providerId and fieldKey are required');
+  }
+  return `ddns:${providerId}:${fieldKey}`;
+}

package/src/nat/secrets/keytar-store.ts

@@ -0,0 +1,67 @@
+import debug from 'debug';
+
+import { NatError } from '../types.js';
+import type { KeytarLike, SecretsStore } from './index.js';
+
+const log = debug('cadre:host:nat-secrets:keytar');
+
+/**
+ * SecretsStore backed by the OS keychain via the `keytar` npm package.
+ *
+ * The keytar module is injected (rather than imported here) so:
+ *   - The native dependency is loaded lazily by `createSecretsStore` and
+ *     unavailable platforms fall through cleanly to the file store.
+ *   - Unit tests can stub the entire keytar surface.
+ */
+export class KeytarSecretsStore implements SecretsStore {
+  constructor(
+    private readonly service: string,
+    private readonly keytar: KeytarLike,
+  ) {}
+
+  async set(account: string, value: string): Promise<void> {
+    try {
+      await this.keytar.setPassword(this.service, account, value);
+    } catch (err) {
+      throw new NatError(
+        'secrets_unavailable',
+        `keytar setPassword failed: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  async get(account: string): Promise<string | null> {
+    try {
+      return await this.keytar.getPassword(this.service, account);
+    } catch (err) {
+      throw new NatError(
+        'secrets_unavailable',
+        `keytar getPassword failed: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  async delete(account: string): Promise<boolean> {
+    try {
+      return await this.keytar.deletePassword(this.service, account);
+    } catch (err) {
+      throw new NatError(
+        'secrets_unavailable',
+        `keytar deletePassword failed: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  async list(): Promise<string[]> {
+    try {
+      const creds = await this.keytar.findCredentials(this.service);
+      log('keytar findCredentials returned %d entries', creds.length);
+      return creds.map((c) => c.account);
+    } catch (err) {
+      throw new NatError(
+        'secrets_unavailable',
+        `keytar findCredentials failed: ${(err as Error).message}`,
+      );
+    }
+  }
+}