@serfab/cadre-host 0.7.1

package/dist/installer/service-host/systemd.d.ts

@@ -0,0 +1,16 @@
+/**
+ * systemd `--user` unit registration.
+ *
+ * Renders the template into `~/.config/systemd/user/cadre-host.service`,
+ * runs `systemctl --user daemon-reload`, `enable --now cadre-host`, and
+ * `loginctl enable-linger <user>` so the unit survives logout / reboot.
+ */
+import type { ServiceHost, ServiceHostContext, ServiceHostStatus } from './types.js';
+export declare class SystemdServiceHost implements ServiceHost {
+    readonly name = "cadre-host";
+    renderUnit(ctx: ServiceHostContext): string;
+    install(ctx: ServiceHostContext): Promise<void>;
+    uninstall(ctx: ServiceHostContext): Promise<void>;
+    restart(ctx: ServiceHostContext): Promise<void>;
+    status(ctx: ServiceHostContext): Promise<ServiceHostStatus>;
+}

package/dist/installer/service-host/systemd.js

@@ -0,0 +1,78 @@
+/**
+ * systemd `--user` unit registration.
+ *
+ * Renders the template into `~/.config/systemd/user/cadre-host.service`,
+ * runs `systemctl --user daemon-reload`, `enable --now cadre-host`, and
+ * `loginctl enable-linger <user>` so the unit survives logout / reboot.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+import debug from 'debug';
+import { renderTemplate } from './template.js';
+import { serviceInstallPath } from '../paths.js';
+const log = debug('cadre:host:installer:systemd');
+const SERVICE_NAME = 'cadre-host';
+export class SystemdServiceHost {
+    constructor() {
+        this.name = SERVICE_NAME;
+    }
+    renderUnit(ctx) {
+        const tmpl = readFileSync(`${ctx.serviceDir}/cadre-host.service.tmpl`, 'utf8');
+        return renderTemplate(tmpl, {
+            NODE_PATH: ctx.nodePath,
+            HOST_JS: ctx.hostJs,
+            DATA_DIR: ctx.dataDir,
+        });
+    }
+    async install(ctx) {
+        const unitPath = serviceInstallPath('linux');
+        const unit = this.renderUnit(ctx);
+        mkdirSync(dirname(unitPath), { recursive: true });
+        writeFileSync(unitPath, unit, { mode: 0o644 });
+        log('wrote %s', unitPath);
+        run('systemctl', ['--user', 'daemon-reload']);
+        run('systemctl', ['--user', 'enable', '--now', SERVICE_NAME]);
+        // enable-linger is opportunistic — it requires `loginctl` and may
+        // fail in containers / minimal images. Don't kill the install for it.
+        const user = userInfo().username;
+        const linger = spawnSync('loginctl', ['enable-linger', user], { stdio: 'inherit' });
+        if (linger.status !== 0) {
+            log('loginctl enable-linger %s failed (status=%s) — service may not run after logout', user, linger.status);
+        }
+    }
+    async uninstall(ctx) {
+        const unitPath = serviceInstallPath('linux');
+        // Stop + disable even if the unit file is missing — covers manual cleanup.
+        spawnSync('systemctl', ['--user', 'stop', SERVICE_NAME], { stdio: 'inherit' });
+        spawnSync('systemctl', ['--user', 'disable', SERVICE_NAME], { stdio: 'inherit' });
+        if (existsSync(unitPath)) {
+            rmSync(unitPath, { force: true });
+            log('removed %s', unitPath);
+        }
+        spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit' });
+        void ctx;
+    }
+    async restart(ctx) {
+        void ctx;
+        run('systemctl', ['--user', 'restart', SERVICE_NAME]);
+    }
+    async status(ctx) {
+        void ctx;
+        const unitPath = serviceInstallPath('linux');
+        const installed = existsSync(unitPath);
+        const result = spawnSync('systemctl', ['--user', 'is-active', SERVICE_NAME], { encoding: 'utf8' });
+        const running = result.status === 0 && result.stdout.trim() === 'active';
+        return { installed, running };
+    }
+}
+function run(cmd, args) {
+    try {
+        execFileSync(cmd, args, { stdio: 'inherit' });
+    }
+    catch (err) {
+        throw new Error(`${cmd} ${args.join(' ')} failed: ${err.message}`);
+    }
+}
+//# sourceMappingURL=systemd.js.map

package/dist/installer/service-host/systemd.js.map

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

package/dist/installer/service-host/template.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tiny `@TOKEN@` substitution. Used to render systemd / launchd unit
+ * files. Throws if any tokens are left after substitution to catch
+ * typos at install time rather than at service-startup time.
+ */
+export declare function renderTemplate(template: string, tokens: Readonly<Record<string, string>>): string;

package/dist/installer/service-host/template.js

@@ -0,0 +1,20 @@
+/**
+ * Tiny `@TOKEN@` substitution. Used to render systemd / launchd unit
+ * files. Throws if any tokens are left after substitution to catch
+ * typos at install time rather than at service-startup time.
+ */
+const TOKEN_RE = /@([A-Z][A-Z0-9_]*)@/g;
+export function renderTemplate(template, tokens) {
+    const rendered = template.replace(TOKEN_RE, (full, key) => {
+        if (!Object.prototype.hasOwnProperty.call(tokens, key)) {
+            throw new Error(`renderTemplate: missing value for token ${full}`);
+        }
+        return tokens[key];
+    });
+    const leftover = rendered.match(TOKEN_RE);
+    if (leftover) {
+        throw new Error(`renderTemplate: unresolved tokens: ${leftover.join(', ')}`);
+    }
+    return rendered;
+}
+//# sourceMappingURL=template.js.map

package/dist/installer/service-host/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/installer/service-host/template.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,QAAQ,GAAG,sBAAsB,CAAC;AAExC,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,MAAwC;IACvF,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAW,EAAE,EAAE;QAChE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/installer/service-host/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Service-host abstraction. The wizard picks a concrete impl by platform
+ * (systemd / launchd / NSSM) and drives it through this common interface.
+ */
+export interface ServiceHostContext {
+    /** Absolute path to node.exe / node. */
+    nodePath: string;
+    /** Absolute path to the cadre-host CLI entrypoint (dist/bin/host.js). */
+    hostJs: string;
+    /** Absolute path to the cadre-host data dir. */
+    dataDir: string;
+    /** Directory containing template files / PowerShell scripts. */
+    serviceDir: string;
+}
+export interface ServiceHostStatus {
+    installed: boolean;
+    running: boolean;
+}
+export interface ServiceHost {
+    /** Stable service name (used for status / logging). */
+    readonly name: string;
+    /** Render unit file(s) and register with the OS service manager. */
+    install(ctx: ServiceHostContext): Promise<void>;
+    /** Stop + deregister. Idempotent: no-op when not installed. */
+    uninstall(ctx: ServiceHostContext): Promise<void>;
+    /**
+     * Restart the running service. Used by the update flow after `npm install -g`
+     * to pick up the new binary. Throws if the OS service manager reports a
+     * non-zero exit — callers are responsible for surfacing that as a warning
+     * (the binary swap already succeeded).
+     */
+    restart(ctx: ServiceHostContext): Promise<void>;
+    /** Cheap status read. */
+    status(ctx: ServiceHostContext): Promise<ServiceHostStatus>;
+    /**
+     * Render the unit-file text without touching the OS. Surfaced for unit
+     * tests; the install() path uses this internally too.
+     */
+    renderUnit(ctx: ServiceHostContext): string | null;
+}

package/dist/installer/service-host/types.js

@@ -0,0 +1,6 @@
+/**
+ * Service-host abstraction. The wizard picks a concrete impl by platform
+ * (systemd / launchd / NSSM) and drives it through this common interface.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/installer/service-host/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/installer/service-host/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/installer/wizard.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Interactive install wizard.
+ *
+ * Pure readline — no extra deps. Each prompt is decomposed into a small
+ * `Prompt` so the test can drive the wizard with a scripted Iterable of
+ * answers. Production code wires the prompts to stdin.
+ */
+import type { SupportedPlatform } from './platform.js';
+export interface WizardDefaults {
+    dataDir: string;
+    uiPort: number;
+    libp2pPort: number;
+    upnpEnabled: boolean;
+}
+export interface WizardAnswers {
+    dataDir: string;
+    uiPort: number;
+    libp2pPort: number;
+    upnpEnabled: boolean;
+    configureDdns: boolean;
+}
+export declare const DEFAULT_UI_PORT = 8765;
+export declare const DEFAULT_LIBP2P_PORT = 4001;
+export declare function defaultsForPlatform(platform: SupportedPlatform): WizardDefaults;
+/**
+ * Drive the wizard with a function that returns the next user answer for
+ * a prompt. Used both by the readline-backed `runWizard` and by tests.
+ */
+export declare function runWizardWith(defaults: WizardDefaults, ask: (label: string, fallback: string) => Promise<string>): Promise<WizardAnswers>;
+/** Production entrypoint — drives the wizard over stdin/stdout. */
+export declare function runWizard(defaults: WizardDefaults): Promise<WizardAnswers>;

package/dist/installer/wizard.js

@@ -0,0 +1,67 @@
+/**
+ * Interactive install wizard.
+ *
+ * Pure readline — no extra deps. Each prompt is decomposed into a small
+ * `Prompt` so the test can drive the wizard with a scripted Iterable of
+ * answers. Production code wires the prompts to stdin.
+ */
+import { createInterface } from 'node:readline';
+import { defaultDataDir } from './paths.js';
+export const DEFAULT_UI_PORT = 8765;
+export const DEFAULT_LIBP2P_PORT = 4001;
+export function defaultsForPlatform(platform) {
+    return {
+        dataDir: defaultDataDir(platform),
+        uiPort: DEFAULT_UI_PORT,
+        libp2pPort: DEFAULT_LIBP2P_PORT,
+        upnpEnabled: true,
+    };
+}
+/**
+ * Drive the wizard with a function that returns the next user answer for
+ * a prompt. Used both by the readline-backed `runWizard` and by tests.
+ */
+export async function runWizardWith(defaults, ask) {
+    const dataDir = (await ask('Data directory', defaults.dataDir)).trim() || defaults.dataDir;
+    const uiPort = parsePort(await ask('UI port (localhost only)', String(defaults.uiPort)), defaults.uiPort);
+    const libp2pPort = parsePort(await ask('Cadre libp2p port', String(defaults.libp2pPort)), defaults.libp2pPort);
+    const upnpEnabled = parseBool(await ask('Attempt UPnP port mapping on this network? [Y/n]', defaults.upnpEnabled ? 'Y' : 'n'), defaults.upnpEnabled);
+    const configureDdns = parseBool(await ask('Configure DDNS now? [y/N]', 'N'), false);
+    return { dataDir, uiPort, libp2pPort, upnpEnabled, configureDdns };
+}
+/** Production entrypoint — drives the wizard over stdin/stdout. */
+export async function runWizard(defaults) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await runWizardWith(defaults, async (label, fallback) => prompt(rl, label, fallback));
+    }
+    finally {
+        rl.close();
+    }
+}
+function prompt(rl, label, fallback) {
+    return new Promise((resolve) => {
+        rl.question(`${label} [${fallback}]: `, (answer) => resolve(answer));
+    });
+}
+function parsePort(input, fallback) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return fallback;
+    const n = Number(trimmed);
+    if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+        throw new Error(`Invalid port: ${input}`);
+    }
+    return n;
+}
+function parseBool(input, fallback) {
+    const trimmed = input.trim().toLowerCase();
+    if (!trimmed)
+        return fallback;
+    if (['y', 'yes', 'true', '1'].includes(trimmed))
+        return true;
+    if (['n', 'no', 'false', '0'].includes(trimmed))
+        return false;
+    throw new Error(`Invalid yes/no answer: ${input}`);
+}
+//# sourceMappingURL=wizard.js.map

package/dist/installer/wizard.js.map

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

package/dist/nat/address-resolver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Build the multiaddrs that should be embedded in invites.
+ *
+ * Inputs are the host's currently-best understanding of its dialable surface:
+ *   - DDNS hostname (`/dns4/<hostname>/...`) when configured AND reachable.
+ *   - Raw external IP (`/ip4/<ip>/...`) when no DDNS but reachable.
+ *   - Whatever libp2p reports otherwise — including any `/p2p-circuit/`
+ *     addresses, once relay-client wiring lands (see follow-up tickets).
+ *
+ * This is intentionally a pure function so it's trivial to unit-test, and so
+ * the NatService can be the only place that knows about settings → multiaddrs.
+ */
+export interface BuildInviteAddressesInput {
+    peerId: string;
+    externalPort: number;
+    ddnsHostname: string | null;
+    externalIp: string | null;
+    reachable: boolean;
+    /** Multiaddrs reported by the underlying libp2p node. */
+    libp2pAddrs: string[];
+}
+export declare function buildInviteAddresses(input: BuildInviteAddressesInput): string[];

package/dist/nat/address-resolver.js

@@ -0,0 +1,31 @@
+export function buildInviteAddresses(input) {
+    const suffix = `/p2p/${input.peerId}`;
+    // DNS path-of-truth: stable across IP changes.
+    if (input.reachable && input.ddnsHostname) {
+        return [`/dns4/${input.ddnsHostname}/tcp/${input.externalPort}${suffix}`];
+    }
+    // Raw IPv4: works when we know our external IP.
+    if (input.reachable && input.externalIp && isIpv4(input.externalIp)) {
+        return [`/ip4/${input.externalIp}/tcp/${input.externalPort}${suffix}`];
+    }
+    // Fallback: whatever libp2p sees. Strip any addresses that lack the
+    // peer suffix and append it for clarity, but otherwise pass through.
+    return input.libp2pAddrs.map((a) => withPeerSuffix(a, input.peerId));
+}
+function withPeerSuffix(addr, peerId) {
+    if (addr.includes(`/p2p/${peerId}`))
+        return addr;
+    if (addr.includes('/p2p/'))
+        return addr; // already has *some* peer
+    return `${addr}/p2p/${peerId}`;
+}
+function isIpv4(s) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
+    if (!m)
+        return false;
+    return m.slice(1).every((octet) => {
+        const n = Number(octet);
+        return n >= 0 && n <= 255;
+    });
+}
+//# sourceMappingURL=address-resolver.js.map

package/dist/nat/address-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-resolver.js","sourceRoot":"","sources":["../../src/nat/address-resolver.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IACnE,MAAM,MAAM,GAAG,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;IACtC,+CAA+C;IAC/C,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QAC1C,OAAO,CAAC,SAAS,KAAK,CAAC,YAAY,QAAQ,KAAK,CAAC,YAAY,GAAG,MAAM,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,gDAAgD;IAChD,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,UAAU,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QACpE,OAAO,CAAC,QAAQ,KAAK,CAAC,UAAU,QAAQ,KAAK,CAAC,YAAY,GAAG,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,oEAAoE;IACpE,qEAAqE;IACrE,OAAO,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,MAAc;IAClD,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,MAAM,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC,CAAE,0BAA0B;IACpE,OAAO,GAAG,IAAI,QAAQ,MAAM,EAAE,CAAC;AACjC,CAAC;AAED,SAAS,MAAM,CAAC,CAAS;IACvB,MAAM,CAAC,GAAG,8CAA8C,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/nat/ddns/duckdns.d.ts

@@ -0,0 +1,12 @@
+import type { DdnsProvider } from './index.js';
+/**
+ * DuckDNS provider.
+ *
+ * Update API: HTTPS GET
+ *   https://www.duckdns.org/update?domains=<subdomain>&token=<token>&ip=<ip>
+ * Response is plain text — `OK` on success, `KO` on failure.
+ *
+ * `hostname` may be supplied as the bare subdomain (`foo`) or the FQDN
+ * (`foo.duckdns.org`); we strip the suffix.
+ */
+export declare const duckDnsProvider: DdnsProvider;

package/dist/nat/ddns/duckdns.js

@@ -0,0 +1,57 @@
+import debug from 'debug';
+import { NatError } from '../types.js';
+const log = debug('cadre:host:nat-ddns:duckdns');
+/**
+ * DuckDNS provider.
+ *
+ * Update API: HTTPS GET
+ *   https://www.duckdns.org/update?domains=<subdomain>&token=<token>&ip=<ip>
+ * Response is plain text — `OK` on success, `KO` on failure.
+ *
+ * `hostname` may be supplied as the bare subdomain (`foo`) or the FQDN
+ * (`foo.duckdns.org`); we strip the suffix.
+ */
+export const duckDnsProvider = {
+    id: 'duckdns',
+    displayName: 'DuckDNS',
+    configFields: [
+        { key: 'token', label: 'DuckDNS token', secret: true },
+    ],
+    async update(config, hostname, ip, deps) {
+        const token = config['token'];
+        if (!token) {
+            throw new NatError('ddns_credentials_missing', 'DuckDNS requires a `token` config value');
+        }
+        const subdomain = stripSuffix(hostname);
+        if (!subdomain) {
+            throw new NatError('invalid_config', `DuckDNS hostname must be a valid subdomain (got: "${hostname}")`);
+        }
+        const url = `https://www.duckdns.org/update?domains=${encodeURIComponent(subdomain)}&token=${encodeURIComponent(token)}&ip=${encodeURIComponent(ip)}`;
+        log('DuckDNS update %s → %s', subdomain, ip);
+        let res;
+        try {
+            res = await deps.fetch(url);
+        }
+        catch (err) {
+            throw new NatError('ddns_update_failed', `DuckDNS request failed: ${err.message}`);
+        }
+        if (!res.ok) {
+            throw new NatError('ddns_update_failed', `DuckDNS HTTP ${res.status}: ${res.statusText}`);
+        }
+        const text = (await res.text()).trim();
+        if (text !== 'OK') {
+            throw new NatError('ddns_update_failed', `DuckDNS returned "${text || '(empty)'}" (expected "OK")`);
+        }
+    },
+};
+const SUFFIX = '.duckdns.org';
+function stripSuffix(hostname) {
+    const trimmed = hostname.trim().toLowerCase();
+    if (trimmed.length === 0)
+        return '';
+    if (trimmed.endsWith(SUFFIX)) {
+        return trimmed.slice(0, -SUFFIX.length);
+    }
+    return trimmed;
+}
+//# sourceMappingURL=duckdns.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"duckdns.js","sourceRoot":"","sources":["../../../src/nat/ddns/duckdns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,MAAM,GAAG,GAAG,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAiB;IAC3C,EAAE,EAAE,SAAS;IACb,WAAW,EAAE,SAAS;IACtB,YAAY,EAAE;QACZ,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE;KACvD;IACD,KAAK,CAAC,MAAM,CACV,MAA8B,EAC9B,QAAgB,EAChB,EAAU,EACV,IAAsB;QAEtB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,QAAQ,CAAC,0BAA0B,EAAE,yCAAyC,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,SAAS,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,QAAQ,CAAC,gBAAgB,EAAE,qDAAqD,QAAQ,IAAI,CAAC,CAAC;QAC1G,CAAC;QAED,MAAM,GAAG,GAAG,0CAA0C,kBAAkB,CAAC,SAAS,CAAC,UAAU,kBAAkB,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC;QACtJ,GAAG,CAAC,wBAAwB,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;QAE7C,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,QAAQ,CAChB,oBAAoB,EACpB,2BAA4B,GAAa,CAAC,OAAO,EAAE,CACpD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,QAAQ,CAChB,oBAAoB,EACpB,gBAAgB,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,UAAU,EAAE,CAChD,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACvC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,IAAI,QAAQ,CAChB,oBAAoB,EACpB,qBAAqB,IAAI,IAAI,SAAS,mBAAmB,CAC1D,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC;AAEF,MAAM,MAAM,GAAG,cAAc,CAAC;AAE9B,SAAS,WAAW,CAAC,QAAgB;IACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/nat/ddns/index.d.ts

@@ -0,0 +1,30 @@
+import { type DdnsConfigField } from '../types.js';
+/** Per-provider runtime dependencies (fetch override for tests). */
+export interface DdnsProviderDeps {
+    fetch: typeof fetch;
+}
+/**
+ * DDNS provider interface. Each provider knows:
+ *   - Its display name + the fields needed to configure it (which fields are
+ *     secrets vs. plain config goes into the SecretsStore / nat.json split).
+ *   - How to push an IP update to the provider's API.
+ *
+ * v1 ships DuckDNS only. New providers drop in by exporting a `DdnsProvider`
+ * and adding an entry to `BUILTIN_PROVIDERS`.
+ */
+export interface DdnsProvider {
+    readonly id: string;
+    readonly displayName: string;
+    readonly configFields: ReadonlyArray<DdnsConfigField>;
+    /** Push `ip` for `hostname`. Throws NatError(ddns_update_failed) on failure. */
+    update(config: Record<string, string>, hostname: string, ip: string, deps: DdnsProviderDeps): Promise<void>;
+}
+/** Built-in DDNS providers. */
+export declare const BUILTIN_PROVIDERS: Readonly<Record<string, DdnsProvider>>;
+/** Look up a provider by ID, throwing NatError(ddns_provider_unknown) if missing. */
+export declare function getProvider(providerId: string): DdnsProvider;
+/** List all built-in providers. */
+export declare function listProviders(): DdnsProvider[];
+export { duckDnsProvider } from './duckdns.js';
+export { DdnsUpdater } from './updater.js';
+export type { DdnsUpdaterOptions, DdnsUpdateOutcome } from './updater.js';

package/dist/nat/ddns/index.js

@@ -0,0 +1,21 @@
+import { NatError } from '../types.js';
+import { duckDnsProvider } from './duckdns.js';
+/** Built-in DDNS providers. */
+export const BUILTIN_PROVIDERS = {
+    duckdns: duckDnsProvider,
+};
+/** Look up a provider by ID, throwing NatError(ddns_provider_unknown) if missing. */
+export function getProvider(providerId) {
+    const p = BUILTIN_PROVIDERS[providerId];
+    if (!p) {
+        throw new NatError('ddns_provider_unknown', `Unknown DDNS provider: ${providerId}. Built-in: ${Object.keys(BUILTIN_PROVIDERS).join(', ')}`);
+    }
+    return p;
+}
+/** List all built-in providers. */
+export function listProviders() {
+    return Object.values(BUILTIN_PROVIDERS);
+}
+export { duckDnsProvider } from './duckdns.js';
+export { DdnsUpdater } from './updater.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/nat/ddns/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AA6B/C,+BAA+B;AAC/B,MAAM,CAAC,MAAM,iBAAiB,GAA2C;IACvE,OAAO,EAAE,eAAe;CACzB,CAAC;AAEF,qFAAqF;AACrF,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,MAAM,CAAC,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,uBAAuB,EACvB,0BAA0B,UAAU,eAAe,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1C,CAAC;AAED,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/nat/ddns/updater.d.ts

@@ -0,0 +1,68 @@
+import type { SecretsStore } from '../secrets/index.js';
+import { type NatDdnsStatus, type NatDdnsSettings } from '../types.js';
+import type { DdnsProvider } from './index.js';
+/** Outcome of a single DDNS update attempt. */
+export interface DdnsUpdateOutcome {
+    attempted: boolean;
+    ok: boolean;
+    ip: string | null;
+    error: string | null;
+    at: Date;
+}
+export interface DdnsUpdaterOptions {
+    /** Current DDNS settings (provider, hostname, externally-managed flag). */
+    settings: NatDdnsSettings;
+    /** Backing credential store. */
+    secrets: SecretsStore;
+    /** Returns the most recently observed external IP (null when unknown). */
+    getExternalIp: () => string | null;
+    /** Fetch override for tests. */
+    fetch?: typeof fetch;
+    /** Provider resolver override (tests can inject fakes). */
+    resolveProvider?: (providerId: string) => DdnsProvider;
+    /** Clock override for tests. */
+    now?: () => Date;
+    /** Timer overrides for tests. */
+    setInterval?: (fn: () => void, ms: number) => NodeJS.Timeout;
+    clearInterval?: (h: NodeJS.Timeout) => void;
+}
+/**
+ * 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 declare class DdnsUpdater {
+    private settings;
+    private readonly secrets;
+    private readonly getExternalIp;
+    private readonly fetchImpl;
+    private readonly resolveProvider;
+    private readonly nowFn;
+    private readonly setIntervalFn;
+    private readonly clearIntervalFn;
+    private timer;
+    private lastPushedIp;
+    private lastOutcome;
+    private started;
+    constructor(opts: DdnsUpdaterOptions);
+    /** Current status (for the NatService snapshot). */
+    getStatus(): NatDdnsStatus;
+    start(): Promise<DdnsUpdateOutcome>;
+    stop(): void;
+    /** Replace settings; restart the loop with the new configuration. */
+    updateSettings(next: NatDdnsSettings): Promise<DdnsUpdateOutcome>;
+    /** Force an immediate update, bypassing the unchanged-IP skip. */
+    forceUpdate(): Promise<DdnsUpdateOutcome>;
+    private shouldUpdate;
+    private scheduleNext;
+    private runOnce;
+    private loadConfig;
+}