@serfab/cadre-host 0.7.1

package/dist/nat/ddns/updater.js

@@ -0,0 +1,194 @@
+import debug from 'debug';
+import { ddnsAccount } from '../secrets/index.js';
+import { NatError } from '../types.js';
+import { getProvider } from './index.js';
+const log = debug('cadre:host:nat-ddns:updater');
+/**
+ * DDNS update loop.
+ *
+ * Lifecycle:
+ *   - `start()`: if a provider is configured AND not externally managed, runs
+ *     an immediate update, then schedules `setInterval(intervalMs)`.
+ *   - On each tick: re-evaluates the IP. If unchanged from the last successful
+ *     update, no provider call. If changed, calls `provider.update`. Errors
+ *     are recorded but the timer keeps ticking.
+ *   - `stop()`: clears the timer. Idempotent.
+ *   - `updateSettings(...)`: swap in new settings, re-starting if needed.
+ *   - `forceUpdate()`: bypass the unchanged-IP check (used by `testReachability`).
+ */
+export class DdnsUpdater {
+    constructor(opts) {
+        this.timer = null;
+        this.lastPushedIp = null;
+        this.lastOutcome = null;
+        this.started = false;
+        this.settings = opts.settings;
+        this.secrets = opts.secrets;
+        this.getExternalIp = opts.getExternalIp;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.resolveProvider = opts.resolveProvider ?? getProvider;
+        this.nowFn = opts.now ?? (() => new Date());
+        this.setIntervalFn = opts.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+        this.clearIntervalFn = opts.clearInterval ?? ((h) => clearInterval(h));
+    }
+    /** Current status (for the NatService snapshot). */
+    getStatus() {
+        return {
+            providerId: this.settings.providerId,
+            hostname: this.settings.hostname,
+            externallyManaged: this.settings.externallyManaged,
+            lastUpdateAt: this.lastOutcome?.at.toISOString() ?? null,
+            lastUpdateOk: this.lastOutcome?.ok ?? null,
+            lastError: this.lastOutcome?.error ?? null,
+        };
+    }
+    async start() {
+        if (this.started) {
+            return this.lastOutcome ?? notAttempted(this.nowFn());
+        }
+        this.started = true;
+        if (!this.shouldUpdate()) {
+            const outcome = notAttempted(this.nowFn());
+            // For an externally-managed entry we still report state, but never push.
+            return outcome;
+        }
+        const outcome = await this.runOnce();
+        this.scheduleNext();
+        return outcome;
+    }
+    stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        if (this.timer) {
+            this.clearIntervalFn(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Replace settings; restart the loop with the new configuration. */
+    async updateSettings(next) {
+        const wasRunning = this.started;
+        this.stop();
+        this.settings = next;
+        this.lastPushedIp = null;
+        if (!wasRunning)
+            return this.lastOutcome ?? notAttempted(this.nowFn());
+        return await this.start();
+    }
+    /** Force an immediate update, bypassing the unchanged-IP skip. */
+    async forceUpdate() {
+        if (!this.shouldUpdate())
+            return notAttempted(this.nowFn());
+        this.lastPushedIp = null;
+        return await this.runOnce();
+    }
+    shouldUpdate() {
+        if (!this.settings.providerId)
+            return false;
+        if (!this.settings.hostname)
+            return false;
+        if (this.settings.externallyManaged)
+            return false;
+        return true;
+    }
+    scheduleNext() {
+        if (this.timer)
+            this.clearIntervalFn(this.timer);
+        this.timer = this.setIntervalFn(() => {
+            void this.runOnce().catch((err) => log('updater tick error: %s', err.message));
+        }, this.settings.intervalMs);
+    }
+    async runOnce() {
+        const ip = this.getExternalIp();
+        if (!ip) {
+            const outcome = {
+                attempted: false,
+                ok: false,
+                ip: null,
+                error: 'external IP unknown',
+                at: this.nowFn(),
+            };
+            this.lastOutcome = outcome;
+            return outcome;
+        }
+        if (ip === this.lastPushedIp) {
+            // Unchanged: no provider call (per DuckDNS guidance: don't re-push).
+            log('DDNS skip: IP unchanged (%s)', ip);
+            return this.lastOutcome ?? notAttempted(this.nowFn());
+        }
+        let provider;
+        try {
+            provider = this.resolveProvider(this.settings.providerId);
+        }
+        catch (err) {
+            const outcome = {
+                attempted: true,
+                ok: false,
+                ip,
+                error: err.message,
+                at: this.nowFn(),
+            };
+            this.lastOutcome = outcome;
+            return outcome;
+        }
+        let config;
+        try {
+            config = await this.loadConfig(provider);
+        }
+        catch (err) {
+            const outcome = {
+                attempted: true,
+                ok: false,
+                ip,
+                error: err.message,
+                at: this.nowFn(),
+            };
+            this.lastOutcome = outcome;
+            return outcome;
+        }
+        try {
+            await provider.update(config, this.settings.hostname, ip, { fetch: this.fetchImpl });
+            this.lastPushedIp = ip;
+            const outcome = {
+                attempted: true,
+                ok: true,
+                ip,
+                error: null,
+                at: this.nowFn(),
+            };
+            this.lastOutcome = outcome;
+            log('DDNS update OK: %s → %s', this.settings.hostname, ip);
+            return outcome;
+        }
+        catch (err) {
+            const outcome = {
+                attempted: true,
+                ok: false,
+                ip,
+                error: err.message,
+                at: this.nowFn(),
+            };
+            this.lastOutcome = outcome;
+            log('DDNS update FAIL: %s', outcome.error);
+            return outcome;
+        }
+    }
+    async loadConfig(provider) {
+        const result = {};
+        for (const field of provider.configFields) {
+            if (!field.secret)
+                continue;
+            const value = await this.secrets.get(ddnsAccount(provider.id, field.key));
+            if (value === null) {
+                throw new NatError('ddns_credentials_missing', `Missing DDNS credential for provider "${provider.id}", field "${field.key}". ` +
+                    `Configure with \`cadre-host nat ddns set ${provider.id}\`.`);
+            }
+            result[field.key] = value;
+        }
+        return result;
+    }
+}
+function notAttempted(at) {
+    return { attempted: false, ok: false, ip: null, error: null, at };
+}
+//# sourceMappingURL=updater.js.map

package/dist/nat/ddns/updater.js.map

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

package/dist/nat/external-ip.d.ts

@@ -0,0 +1,62 @@
+/** Result of an external-IP detection cycle. */
+export interface ExternalIpResult {
+    /** IP reported by the upstream router (UPnP/NAT-PMP gateway), if reachable. */
+    routerIp: string | null;
+    /** IP reported by a public IP echo service. */
+    publicIp: string | null;
+    /**
+     * True when both probes succeeded AND returned different addresses, which
+     * is the textbook CGNAT signature: the router thinks its WAN address is
+     * private to the carrier.
+     */
+    cgnat: boolean;
+    /** When this snapshot was taken. */
+    detectedAt: Date;
+}
+/** Abstract router-side probe (gateway WAN address). */
+export type RouterIpProbe = () => Promise<string | null>;
+export interface ExternalIpDetectorOptions {
+    /** Probe the local router's external IP (typically via the port mapper). */
+    routerProbe?: RouterIpProbe;
+    /** Public IP service endpoints. */
+    publicIpUrls?: ReadonlyArray<string>;
+    /** Fetch override (tests stub this). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Clock override for tests. */
+    now?: () => Date;
+    /** Per-request timeout in ms (default 5000). */
+    requestTimeoutMs?: number;
+}
+/**
+ * External-IP detector.
+ *
+ * Two independent sources:
+ *   - The router (queried via the port mapper's gateway interface). May be
+ *     unavailable if UPnP is off or the upstream device doesn't expose
+ *     WANIPConnection.
+ *   - A public HTTPS echo service (api.ipify.org and friends). May be
+ *     unreachable on a firewalled / offline machine.
+ *
+ * When both succeed AND disagree, we flag CGNAT. The check is heuristic — a
+ * fast-changing IP, a sliced VPN, or an IPv6-only public probe could all
+ * trigger a false positive. The verdict is informational, not enforced.
+ */
+export declare class ExternalIpDetector {
+    private readonly routerProbe;
+    private readonly publicIpUrls;
+    private readonly fetchImpl;
+    private readonly nowFn;
+    private readonly requestTimeoutMs;
+    constructor(opts?: ExternalIpDetectorOptions);
+    /** Run both probes in parallel and return the snapshot. */
+    detect(): Promise<ExternalIpResult>;
+    private runRouterProbe;
+    private runPublicProbe;
+    private tryPublicUrl;
+}
+/**
+ * Liberal IP validation — accepts both IPv4 and IPv6 in dotted/colon form.
+ * Tighter validation lives at the consumer (`nat-service` checks for IPv4
+ * before building an `/ip4/` multiaddr).
+ */
+export declare function isPlausibleIp(s: string): boolean;

package/dist/nat/external-ip.js

@@ -0,0 +1,114 @@
+import debug from 'debug';
+const log = debug('cadre:host:nat-external-ip');
+/** Public IP echo endpoints. Tried in order; first success wins. */
+const DEFAULT_PUBLIC_IP_URLS = [
+    'https://api.ipify.org',
+    'https://ifconfig.me/ip',
+    'https://icanhazip.com',
+];
+/**
+ * External-IP detector.
+ *
+ * Two independent sources:
+ *   - The router (queried via the port mapper's gateway interface). May be
+ *     unavailable if UPnP is off or the upstream device doesn't expose
+ *     WANIPConnection.
+ *   - A public HTTPS echo service (api.ipify.org and friends). May be
+ *     unreachable on a firewalled / offline machine.
+ *
+ * When both succeed AND disagree, we flag CGNAT. The check is heuristic — a
+ * fast-changing IP, a sliced VPN, or an IPv6-only public probe could all
+ * trigger a false positive. The verdict is informational, not enforced.
+ */
+export class ExternalIpDetector {
+    constructor(opts = {}) {
+        this.routerProbe = opts.routerProbe;
+        this.publicIpUrls = opts.publicIpUrls ?? DEFAULT_PUBLIC_IP_URLS;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.nowFn = opts.now ?? (() => new Date());
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? 5000;
+    }
+    /** Run both probes in parallel and return the snapshot. */
+    async detect() {
+        const [routerIp, publicIp] = await Promise.all([
+            this.runRouterProbe(),
+            this.runPublicProbe(),
+        ]);
+        const cgnat = routerIp !== null && publicIp !== null && routerIp !== publicIp;
+        if (cgnat) {
+            log('CGNAT detected: routerIp=%s, publicIp=%s', routerIp, publicIp);
+        }
+        return {
+            routerIp,
+            publicIp,
+            cgnat,
+            detectedAt: this.nowFn(),
+        };
+    }
+    async runRouterProbe() {
+        if (!this.routerProbe)
+            return null;
+        try {
+            const ip = await this.routerProbe();
+            return ip && isPlausibleIp(ip) ? ip : null;
+        }
+        catch (err) {
+            log('routerProbe failed: %s', err.message);
+            return null;
+        }
+    }
+    async runPublicProbe() {
+        for (const url of this.publicIpUrls) {
+            const ip = await this.tryPublicUrl(url);
+            if (ip)
+                return ip;
+        }
+        return null;
+    }
+    async tryPublicUrl(url) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            const res = await this.fetchImpl(url, { signal: controller.signal });
+            if (!res.ok) {
+                log('public IP probe %s returned %d', url, res.status);
+                return null;
+            }
+            const text = (await res.text()).trim();
+            if (!isPlausibleIp(text)) {
+                log('public IP probe %s returned non-IP: %s', url, text.slice(0, 64));
+                return null;
+            }
+            return text;
+        }
+        catch (err) {
+            log('public IP probe %s failed: %s', url, err.message);
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Liberal IP validation — accepts both IPv4 and IPv6 in dotted/colon form.
+ * Tighter validation lives at the consumer (`nat-service` checks for IPv4
+ * before building an `/ip4/` multiaddr).
+ */
+export function isPlausibleIp(s) {
+    if (!s || s.length > 45)
+        return false;
+    // IPv4: 4 dotted octets, 0-255 each.
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
+    if (v4) {
+        return v4.slice(1).every((octet) => {
+            const n = Number(octet);
+            return n >= 0 && n <= 255;
+        });
+    }
+    // IPv6: very liberal — at least two colons, only hex/colon characters.
+    if (/^[0-9a-fA-F:]+$/.test(s) && s.split(':').length >= 3)
+        return true;
+    return false;
+}
+//# sourceMappingURL=external-ip.js.map

package/dist/nat/external-ip.js.map

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

package/dist/nat/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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-local-ui`).
+ */
+export { NatService, createNatHandlers } from './nat-service.js';
+export type { NatServiceOptions, CadreNodeLike } from './nat-service.js';
+export { NatStore } from './nat-store.js';
+export { NatError, } from './types.js';
+export type { NatStatusSnapshot, NatDdnsStatus, NatSettingsFile, NatDdnsSettings, NatHandlers, NatErrorCode, PortForwardMode, DirectReachability, DdnsProviderInfo, DdnsConfigField, } from './types.js';
+export { ExternalIpDetector, isPlausibleIp, } from './external-ip.js';
+export type { ExternalIpResult, RouterIpProbe, ExternalIpDetectorOptions, } from './external-ip.js';
+export { PortMapperService, createDefaultPortMapper, DEFAULT_LEASE_TTL_MS, DEFAULT_REFRESH_MS, } from './port-mapper.js';
+export type { PortMapper, PortMappingResult, PortMapOptions, PortMapperState, PortMapperServiceOptions, } from './port-mapper.js';
+export { evaluateReachability } from './reachability.js';
+export { buildInviteAddresses } from './address-resolver.js';
+export type { BuildInviteAddressesInput } 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';

package/dist/nat/index.js

@@ -0,0 +1,16 @@
+/**
+ * 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-local-ui`).
+ */
+export { NatService, createNatHandlers } from './nat-service.js';
+export { NatStore } from './nat-store.js';
+export { NatError, } from './types.js';
+export { ExternalIpDetector, isPlausibleIp, } from './external-ip.js';
+export { PortMapperService, createDefaultPortMapper, DEFAULT_LEASE_TTL_MS, DEFAULT_REFRESH_MS, } from './port-mapper.js';
+export { evaluateReachability } from './reachability.js';
+export { buildInviteAddresses } from './address-resolver.js';
+export { BUILTIN_PROVIDERS, getProvider, listProviders, duckDnsProvider, DdnsUpdater, } from './ddns/index.js';
+export { KeytarSecretsStore, FileSecretsStore, createSecretsStore, ddnsAccount, KEYTAR_SERVICE, } from './secrets/index.js';
+//# sourceMappingURL=index.js.map

package/dist/nat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/nat/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEjE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EACL,QAAQ,GACT,MAAM,YAAY,CAAC;AAapB,OAAO,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAOzB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,GACf,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,101 @@
+import { type DdnsProviderInfo, type NatHandlers, type NatSettingsFile, type NatStatusSnapshot } from './types.js';
+import { NatStore } from './nat-store.js';
+import { ExternalIpDetector } from './external-ip.js';
+import { type PortMapper } from './port-mapper.js';
+import { type SecretsStore } from './secrets/index.js';
+/**
+ * Minimal slice of CadreNode that NatService needs — defined as an interface
+ * so tests can inject a mock without a real libp2p stack. Mirrors
+ * `CadreNodeLike` in `auth/trust-circle.ts`.
+ */
+export interface CadreNodeLike {
+    /** Returns this node's peer ID (libp2p) as a string. */
+    getPeerId(): string;
+    /** Returns the current observed multiaddrs from libp2p. */
+    getMultiaddrs(): string[];
+}
+export interface NatServiceOptions {
+    /** Cadre-host root directory (same one orchestrator + trust-circle use). */
+    rootDir: string;
+    /** libp2p node — used for peer ID and the libp2p multiaddrs fallback. */
+    cadreNode: CadreNodeLike;
+    /** Clock override for tests. */
+    now?: () => Date;
+    /** Fetch override for tests. */
+    fetch?: typeof fetch;
+    /** Test-only: stub the keytar/file-store. Default: createSecretsStore. */
+    secretsStore?: SecretsStore;
+    /** Test-only: stub the port mapper. Default: createDefaultPortMapper(). */
+    portMapper?: PortMapper;
+    /** Test-only: stub the external-IP detector. */
+    externalIpDetector?: ExternalIpDetector;
+    /** Optional: re-use an existing NatStore (mostly for tests). */
+    store?: NatStore;
+}
+/**
+ * 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 declare class NatService {
+    private readonly cadreNode;
+    private readonly store;
+    private readonly nowFn;
+    private readonly fetchImpl;
+    private secretsStore;
+    private portMapper;
+    /** Caller-supplied detector — used as-is when present (skips the auto router-probe stitch). */
+    private readonly injectedDetector;
+    private portService;
+    private ddnsUpdater;
+    private currentSettings;
+    private latestIp;
+    private lastTestedAt;
+    private started;
+    private readonly secretsRootDir;
+    constructor(opts: NatServiceOptions);
+    /** Initial start: port mapping → IP detect → DDNS. Idempotent. */
+    start(): Promise<void>;
+    /** Release the port mapping and clear timers. Idempotent. */
+    stop(): Promise<void>;
+    /** Cheap read of the current snapshot. */
+    getStatus(): NatStatusSnapshot;
+    /** Re-run the IP probe + port-mapper verify, then return a fresh snapshot. */
+    testReachability(): Promise<NatStatusSnapshot>;
+    /** Build the multiaddrs to embed in invites. */
+    getInviteAddresses(): Promise<string[]>;
+    /** Current settings (cheap read; for handlers to surface to UI). */
+    getSettings(): NatSettingsFile;
+    /** Replace settings; persists to disk and reconfigures the runtime. */
+    putSettings(patch: Partial<Omit<NatSettingsFile, 'version'>>): Promise<NatStatusSnapshot>;
+    /**
+     * Set DDNS configuration and persist secret values into the SecretsStore.
+     * Throws if the provider is unknown or required secrets are missing.
+     */
+    putDdns(body: {
+        providerId: string;
+        hostname: string;
+        config: Record<string, string>;
+        externallyManaged?: boolean;
+    }): Promise<NatStatusSnapshot>;
+    /** List available DDNS providers (UI listing for configuration). */
+    listDdnsProviders(): DdnsProviderInfo[];
+    private startPortService;
+    private detectIp;
+    private disabledPortState;
+}
+/**
+ * Wrap a NatService into the typed handler shape consumed by
+ * `cadre-host-local-ui`. Mirrors `createTrustCircleHandlers`.
+ */
+export declare function createNatHandlers(service: NatService): NatHandlers;