@serfab/cadre-host 0.7.1

package/dist/nat/nat-service.js

@@ -0,0 +1,284 @@
+import debug from 'debug';
+import { NatError, } from './types.js';
+import { NatStore } from './nat-store.js';
+import { ExternalIpDetector } from './external-ip.js';
+import { PortMapperService, createDefaultPortMapper, } from './port-mapper.js';
+import { evaluateReachability } from './reachability.js';
+import { DdnsUpdater } from './ddns/updater.js';
+import { getProvider, listProviders } from './ddns/index.js';
+import { buildInviteAddresses, } from './address-resolver.js';
+import { createSecretsStore, ddnsAccount } from './secrets/index.js';
+const log = debug('cadre:host:nat-service');
+/**
+ * NatService — orchestrates port mapping, external-IP detection, DDNS updates,
+ * and address resolution for invites.
+ *
+ * Lifecycle:
+ *   - `start()`: load settings, install port mapping (if upnpEnabled), detect
+ *     external IP, kick off DDNS loop.
+ *   - `stop()`: release port mapping, stop DDNS timer.
+ *   - `getStatus()`: build a fresh status snapshot from internal state (cheap).
+ *   - `testReachability()`: re-run the IP + verify cycle and the heuristic.
+ *   - `getInviteAddresses()`: build the multiaddrs to embed in invites.
+ *
+ * NatService is library + lifecycle only. The long-running process that owns
+ * it is `cadre-host-local-ui` (see docs/cadre-host.md and the ticket header).
+ */
+export class NatService {
+    constructor(opts) {
+        // Built once start() completes.
+        this.portService = null;
+        this.ddnsUpdater = null;
+        this.latestIp = null;
+        this.lastTestedAt = null;
+        this.started = false;
+        this.cadreNode = opts.cadreNode;
+        this.store = opts.store ?? new NatStore(opts.rootDir);
+        this.nowFn = opts.now ?? (() => new Date());
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.secretsStore = opts.secretsStore ?? null;
+        this.portMapper = opts.portMapper ?? null;
+        this.injectedDetector = opts.externalIpDetector ?? null;
+        this.secretsRootDir = opts.rootDir;
+        this.currentSettings = this.store.load();
+    }
+    /** Initial start: port mapping → IP detect → DDNS. Idempotent. */
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        // 1. Secrets store (lazy if not injected).
+        if (!this.secretsStore) {
+            this.secretsStore = await createSecretsStore(this.secretsRootDir);
+        }
+        // 2. Port mapping.
+        await this.startPortService();
+        // 3. External IP detection.
+        await this.detectIp();
+        // 4. DDNS updater.
+        this.ddnsUpdater = new DdnsUpdater({
+            settings: this.currentSettings.ddns,
+            secrets: this.secretsStore,
+            getExternalIp: () => this.latestIp?.publicIp ?? this.latestIp?.routerIp ?? null,
+            fetch: this.fetchImpl,
+            now: this.nowFn,
+        });
+        await this.ddnsUpdater.start();
+    }
+    /** Release the port mapping and clear timers. Idempotent. */
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        try {
+            this.ddnsUpdater?.stop();
+        }
+        catch (err) {
+            log('ddns stop failed: %s', err.message);
+        }
+        this.ddnsUpdater = null;
+        try {
+            await this.portService?.stop();
+        }
+        catch (err) {
+            log('port-service stop failed: %s', err.message);
+        }
+        this.portService = null;
+    }
+    /** Cheap read of the current snapshot. */
+    getStatus() {
+        const portState = this.portService?.getState() ?? this.disabledPortState();
+        const externalIp = this.latestIp?.publicIp ?? this.latestIp?.routerIp ?? null;
+        const ddns = this.ddnsUpdater?.getStatus() ?? {
+            providerId: this.currentSettings.ddns.providerId,
+            hostname: this.currentSettings.ddns.hostname,
+            externallyManaged: this.currentSettings.ddns.externallyManaged,
+            lastUpdateAt: null,
+            lastUpdateOk: null,
+            lastError: null,
+        };
+        return {
+            portMode: this.currentSettings.upnpEnabled ? portState.mode : 'disabled',
+            externalPort: portState.externalPort,
+            internalPort: portState.internalPort,
+            routerExternalIp: portState.routerExternalIp,
+            mappingLeaseExpiresAt: portState.leaseExpiresAt?.toISOString() ?? null,
+            externalIp,
+            externalIpDetectedAt: this.latestIp?.detectedAt.toISOString() ?? null,
+            cgnatDetected: this.latestIp?.cgnat ?? false,
+            directReachability: evaluateReachability({
+                portMode: portState.mode,
+                cgnatDetected: this.latestIp?.cgnat ?? false,
+            }),
+            lastTestedAt: this.lastTestedAt?.toISOString() ?? null,
+            ddns,
+        };
+    }
+    /** Re-run the IP probe + port-mapper verify, then return a fresh snapshot. */
+    async testReachability() {
+        if (this.portService) {
+            await this.portService.refresh().catch((err) => log('refresh err: %s', err.message));
+        }
+        await this.detectIp();
+        this.lastTestedAt = this.nowFn();
+        // Best-effort DDNS push when the IP just changed.
+        if (this.ddnsUpdater) {
+            await this.ddnsUpdater.forceUpdate().catch((err) => log('ddns forceUpdate err: %s', err.message));
+        }
+        return this.getStatus();
+    }
+    /** Build the multiaddrs to embed in invites. */
+    async getInviteAddresses() {
+        const peerId = this.cadreNode.getPeerId();
+        const status = this.getStatus();
+        const input = {
+            peerId,
+            externalPort: status.externalPort,
+            ddnsHostname: status.ddns.hostname,
+            externalIp: status.externalIp,
+            reachable: status.directReachability === 'reachable',
+            libp2pAddrs: this.cadreNode.getMultiaddrs(),
+        };
+        return buildInviteAddresses(input);
+    }
+    /** Current settings (cheap read; for handlers to surface to UI). */
+    getSettings() {
+        return this.currentSettings;
+    }
+    /** Replace settings; persists to disk and reconfigures the runtime. */
+    async putSettings(patch) {
+        const next = this.store.update(patch);
+        const upnpChanged = next.upnpEnabled !== this.currentSettings.upnpEnabled;
+        const portChanged = next.externalPort !== this.currentSettings.externalPort ||
+            next.internalPort !== this.currentSettings.internalPort;
+        const ddnsChanged = next.ddns.providerId !== this.currentSettings.ddns.providerId ||
+            next.ddns.hostname !== this.currentSettings.ddns.hostname ||
+            next.ddns.externallyManaged !== this.currentSettings.ddns.externallyManaged ||
+            next.ddns.intervalMs !== this.currentSettings.ddns.intervalMs;
+        this.currentSettings = next;
+        if (this.started) {
+            if (upnpChanged || portChanged) {
+                try {
+                    await this.portService?.stop();
+                }
+                catch { /* ignore */ }
+                this.portService = null;
+                await this.startPortService();
+            }
+            if (ddnsChanged && this.ddnsUpdater) {
+                await this.ddnsUpdater.updateSettings(next.ddns);
+            }
+        }
+        return this.getStatus();
+    }
+    /**
+     * Set DDNS configuration and persist secret values into the SecretsStore.
+     * Throws if the provider is unknown or required secrets are missing.
+     */
+    async putDdns(body) {
+        if (!body || typeof body.providerId !== 'string' || typeof body.hostname !== 'string') {
+            throw new NatError('invalid_config', 'providerId and hostname are required');
+        }
+        const provider = getProvider(body.providerId);
+        if (!this.secretsStore) {
+            throw new NatError('secrets_unavailable', 'secrets store not initialised; call start() first');
+        }
+        // Persist secrets.
+        for (const field of provider.configFields) {
+            if (!field.secret)
+                continue;
+            const value = body.config[field.key];
+            if (typeof value !== 'string' || value.length === 0) {
+                throw new NatError('ddns_credentials_missing', `Missing value for required secret field "${field.key}" of provider "${provider.id}"`);
+            }
+            await this.secretsStore.set(ddnsAccount(provider.id, field.key), value);
+        }
+        // Update nat.json.
+        const externallyManaged = body.externallyManaged ?? false;
+        return await this.putSettings({
+            ddns: {
+                providerId: provider.id,
+                hostname: body.hostname,
+                externallyManaged,
+                intervalMs: this.currentSettings.ddns.intervalMs,
+            },
+        });
+    }
+    /** List available DDNS providers (UI listing for configuration). */
+    listDdnsProviders() {
+        return listProviders().map((p) => ({
+            id: p.id,
+            displayName: p.displayName,
+            configFields: p.configFields,
+        }));
+    }
+    // --- private ---
+    async startPortService() {
+        if (!this.currentSettings.upnpEnabled) {
+            log('UPnP disabled by settings; skipping port mapping');
+            return;
+        }
+        let mapper = this.portMapper;
+        if (!mapper) {
+            try {
+                mapper = await createDefaultPortMapper();
+                this.portMapper = mapper;
+            }
+            catch (err) {
+                log('default port mapper unavailable: %s', err.message);
+                return;
+            }
+        }
+        this.portService = new PortMapperService({
+            mapper,
+            externalPort: this.currentSettings.externalPort,
+            internalPort: this.currentSettings.internalPort,
+            now: this.nowFn,
+        });
+        await this.portService.start();
+    }
+    async detectIp() {
+        // If the caller injected a detector (typically a test stub), use it as-is —
+        // don't second-guess them by stitching in the port mapper's router probe.
+        const detector = this.injectedDetector ?? (this.portMapper
+            ? new ExternalIpDetector({
+                fetch: this.fetchImpl,
+                now: this.nowFn,
+                routerProbe: async () => this.portMapper.externalIp(),
+            })
+            : new ExternalIpDetector({
+                fetch: this.fetchImpl,
+                now: this.nowFn,
+            }));
+        try {
+            this.latestIp = await detector.detect();
+        }
+        catch (err) {
+            log('detectIp failed: %s', err.message);
+        }
+    }
+    disabledPortState() {
+        return {
+            mode: this.currentSettings.upnpEnabled ? 'failed' : 'disabled',
+            externalPort: this.currentSettings.externalPort,
+            internalPort: this.currentSettings.internalPort,
+            routerExternalIp: null,
+            leaseExpiresAt: null,
+            lastError: null,
+        };
+    }
+}
+/**
+ * Wrap a NatService into the typed handler shape consumed by
+ * `cadre-host-local-ui`. Mirrors `createTrustCircleHandlers`.
+ */
+export function createNatHandlers(service) {
+    return {
+        async getStatus() { return service.getStatus(); },
+        async testReachability() { return await service.testReachability(); },
+        async listDdnsProviders() { return service.listDdnsProviders(); },
+        async putDdns(body) { return await service.putDdns(body); },
+        async putSettings(body) { return await service.putSettings(body); },
+    };
+}
+//# sourceMappingURL=nat-service.js.map

package/dist/nat/nat-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nat-service.js","sourceRoot":"","sources":["../../src/nat/nat-service.ts"],"names":[],"mappings":"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"}

package/dist/nat/nat-store.d.ts

@@ -0,0 +1,19 @@
+import { type NatSettingsFile } from './types.js';
+/**
+ * Atomic JSON store for `nat.json`. Mirrors `TrustCircleStore` — write to
+ * `<path>.tmp`, then rename.
+ *
+ * Concurrency assumption: only one cadre-host process owns a given rootDir.
+ */
+export declare class NatStore {
+    private readonly path;
+    private cache;
+    constructor(rootDir: string);
+    filePath(): string;
+    /** Load (with caching). A missing file returns defaults. */
+    load(): NatSettingsFile;
+    /** Persist current settings atomically. */
+    save(state: NatSettingsFile): void;
+    /** Patch and persist (validation lives here). */
+    update(patch: Partial<Omit<NatSettingsFile, 'version'>>): NatSettingsFile;
+}

package/dist/nat/nat-store.js

@@ -0,0 +1,136 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+import { NatError } from './types.js';
+const log = debug('cadre:host:nat-store');
+const FILE_VERSION = 1;
+/** Default port (libp2p TCP default). */
+const DEFAULT_PORT = 4001;
+/** Default DDNS update interval (5 minutes). */
+const DEFAULT_DDNS_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * Atomic JSON store for `nat.json`. Mirrors `TrustCircleStore` — write to
+ * `<path>.tmp`, then rename.
+ *
+ * Concurrency assumption: only one cadre-host process owns a given rootDir.
+ */
+export class NatStore {
+    constructor(rootDir) {
+        this.cache = null;
+        mkdirSync(rootDir, { recursive: true });
+        this.path = join(rootDir, 'nat.json');
+    }
+    filePath() {
+        return this.path;
+    }
+    /** Load (with caching). A missing file returns defaults. */
+    load() {
+        if (this.cache)
+            return this.cache;
+        if (!existsSync(this.path)) {
+            this.cache = defaultSettings();
+            return this.cache;
+        }
+        let raw;
+        try {
+            raw = readFileSync(this.path, 'utf8');
+        }
+        catch (err) {
+            throw new NatError('storage_error', `failed to read nat file at ${this.path}: ${err.message}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new NatError('storage_error', `nat file at ${this.path} is not valid JSON: ${err.message}`);
+        }
+        if (!isNatSettingsFile(parsed)) {
+            throw new NatError('storage_error', `nat file at ${this.path} has unexpected shape`);
+        }
+        this.cache = parsed;
+        return this.cache;
+    }
+    /** Persist current settings atomically. */
+    save(state) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const next = { ...state, version: FILE_VERSION };
+        const payload = JSON.stringify(next, null, 2);
+        const tmp = `${this.path}.tmp`;
+        writeFileSync(tmp, payload, { encoding: 'utf8' });
+        renameSync(tmp, this.path);
+        this.cache = next;
+        log('saved nat.json (port=%d, ddns=%s) to %s', next.externalPort, next.ddns.providerId ?? '(none)', this.path);
+    }
+    /** Patch and persist (validation lives here). */
+    update(patch) {
+        const current = this.load();
+        const merged = {
+            ...current,
+            ...patch,
+            ddns: { ...current.ddns, ...(patch.ddns ?? {}) },
+            version: FILE_VERSION,
+        };
+        validate(merged);
+        this.save(merged);
+        return merged;
+    }
+}
+function defaultSettings() {
+    return {
+        version: FILE_VERSION,
+        externalPort: DEFAULT_PORT,
+        internalPort: DEFAULT_PORT,
+        upnpEnabled: true,
+        ddns: defaultDdns(),
+    };
+}
+function defaultDdns() {
+    return {
+        providerId: null,
+        hostname: null,
+        externallyManaged: false,
+        intervalMs: DEFAULT_DDNS_INTERVAL_MS,
+    };
+}
+function isNatSettingsFile(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const obj = v;
+    if (obj.version !== FILE_VERSION)
+        return false;
+    if (typeof obj.externalPort !== 'number' || typeof obj.internalPort !== 'number')
+        return false;
+    if (typeof obj.upnpEnabled !== 'boolean')
+        return false;
+    const ddns = obj.ddns;
+    if (!ddns || typeof ddns !== 'object')
+        return false;
+    if (ddns.providerId !== null && typeof ddns.providerId !== 'string')
+        return false;
+    if (ddns.hostname !== null && typeof ddns.hostname !== 'string')
+        return false;
+    if (typeof ddns.externallyManaged !== 'boolean')
+        return false;
+    if (typeof ddns.intervalMs !== 'number')
+        return false;
+    return true;
+}
+function validate(s) {
+    if (!Number.isInteger(s.externalPort) || s.externalPort < 1 || s.externalPort > 65535) {
+        throw new NatError('invalid_config', `externalPort must be 1-65535, got ${s.externalPort}`);
+    }
+    if (!Number.isInteger(s.internalPort) || s.internalPort < 1 || s.internalPort > 65535) {
+        throw new NatError('invalid_config', `internalPort must be 1-65535, got ${s.internalPort}`);
+    }
+    if (!Number.isFinite(s.ddns.intervalMs) || s.ddns.intervalMs < 1000) {
+        throw new NatError('invalid_config', `ddns.intervalMs must be >= 1000ms, got ${s.ddns.intervalMs}`);
+    }
+    if (s.ddns.providerId !== null && s.ddns.providerId.length === 0) {
+        throw new NatError('invalid_config', 'ddns.providerId must be a non-empty string or null');
+    }
+    if (s.ddns.hostname !== null && s.ddns.hostname.length === 0) {
+        throw new NatError('invalid_config', 'ddns.hostname must be a non-empty string or null');
+    }
+}
+//# sourceMappingURL=nat-store.js.map

package/dist/nat/nat-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nat-store.js","sourceRoot":"","sources":["../../src/nat/nat-store.ts"],"names":[],"mappings":"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"}

package/dist/nat/port-mapper.d.ts

@@ -0,0 +1,98 @@
+import { type PortForwardMode } from './types.js';
+/** Default lease TTL: 1 hour. The router must keep our mapping at least this long. */
+export declare const DEFAULT_LEASE_TTL_MS: number;
+/** Default refresh cadence: half the TTL, so two refreshes per lease. */
+export declare const DEFAULT_REFRESH_MS: number;
+/** 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>;
+/**
+ * Default factory: loads @achingbrain/nat-port-mapper. Wrapped in dynamic
+ * import so a missing dep at install time doesn't crash the package.
+ */
+export declare function createDefaultPortMapper(opts?: {
+    description?: string;
+    ttlMs?: number;
+}): Promise<PortMapper>;
+/** 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 declare class PortMapperService {
+    private readonly mapper;
+    private readonly externalPort;
+    private readonly internalPort;
+    private readonly protocol;
+    private readonly ttlMs;
+    private readonly refreshMs;
+    private readonly nowFn;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private state;
+    private refreshHandle;
+    private started;
+    constructor(opts: PortMapperServiceOptions);
+    getState(): PortMapperState;
+    /** Install the mapping and schedule periodic refresh. */
+    start(): Promise<void>;
+    /** Release the mapping and clear timers. Idempotent. */
+    stop(): Promise<void>;
+    /** Force an immediate verify+refresh cycle (used by testReachability). */
+    refresh(): Promise<PortMapperState>;
+    private scheduleRefresh;
+    private installMapping;
+}