@serfab/cadre-host 0.7.1

package/service/README.md

@@ -0,0 +1,86 @@
+# Cadre Host Service Units
+
+Host cadre-host as a per-user system service. All three units are configured
+so that **a clean exit (code 0) is final** — `cadre-host uninstall` (or any
+explicit `systemctl stop` / `nssm stop`) leaves the service stopped. Crashes
+still trigger a restart.
+
+| Platform | File | Service host |
+| -------- | ---- | ------------ |
+| Linux    | [`cadre-host.service.tmpl`](./cadre-host.service.tmpl)             | systemd (user) |
+| macOS    | [`com.serfab.cadre-host.plist.tmpl`](./com.serfab.cadre-host.plist.tmpl) | launchd (LaunchAgent) |
+| Windows  | [`install-service.ps1`](./install-service.ps1) / [`uninstall-service.ps1`](./uninstall-service.ps1) | NSSM |
+
+The `.tmpl` files contain `@TOKEN@` placeholders that the installer
+substitutes at install time (`@NODE_PATH@`, `@HOST_JS@`, `@DATA_DIR@`).
+Inspect the rendered files under `~/.config/systemd/user/cadre-host.service`
+or `~/Library/LaunchAgents/com.serfab.cadre-host.plist` after running
+`cadre-host install`.
+
+## Scope (v1)
+
+**Per-user install only.** The systemd unit is installed under the user's
+control (`systemctl --user`), the launchd unit is a `LaunchAgent` (not a
+`LaunchDaemon`), and NSSM runs as the current user.
+
+A `--system` flag is accepted by `cadre-host install` but currently errors
+out — running cadre-host as a dedicated system user requires more work
+around data-dir ownership and capability dropping. Tracked separately.
+
+## Linux (systemd) — manual smoke
+
+```bash
+# Render + install + enable + start in one go:
+cadre-host install --non-interactive --data-dir ~/.local/share/cadre-host
+
+# After install, the unit lives at:
+#   ~/.config/systemd/user/cadre-host.service
+# Inspect status:
+systemctl --user status cadre-host
+journalctl --user -u cadre-host -f
+```
+
+`Restart=on-failure` + `RestartPreventExitStatus=0` make exit 0 final.
+
+The installer also runs `loginctl enable-linger <user>` so the unit survives
+logout / reboot.
+
+## macOS (launchd) — manual smoke
+
+```bash
+cadre-host install --non-interactive --data-dir "$HOME/Library/Application Support/CadreHost"
+
+# After install, the plist lives at:
+#   ~/Library/LaunchAgents/com.serfab.cadre-host.plist
+launchctl print gui/$(id -u)/com.serfab.cadre-host
+tail -f "$HOME/Library/Application Support/CadreHost/logs/out.log"
+```
+
+`KeepAlive.SuccessfulExit = false` plus `KeepAlive.Crashed = true` mean a
+clean exit stays down while a crash is relaunched.
+
+## Windows (NSSM) — manual smoke
+
+Install [NSSM](https://nssm.cc/download) and put `nssm.exe` on PATH first.
+
+```powershell
+cadre-host install --non-interactive --data-dir $env:LocalAppData\CadreHost
+
+# After install, inspect the service:
+nssm.exe status CadreHost
+Get-Service CadreHost
+Get-Content $env:LocalAppData\CadreHost\logs\out.log -Tail 30 -Wait
+```
+
+`AppExit 0 Exit` tells NSSM not to restart on clean exit; other exit codes
+are handled by `AppExit Default Restart` with a 5-second delay and a
+10-second throttle. NSSM is **not** bundled with the npm package; the
+standalone-binary distribution (see `tickets/backlog/cadre-host-standalone-binary.md`)
+will ship it.
+
+## CI gap
+
+Cross-platform CI does **not** invoke `systemctl --user enable`,
+`launchctl bootstrap`, or `nssm install`. The installer's unit-rendering
+logic is covered by unit tests; the actual service-host registration must
+be smoke-tested manually on each platform before tagging a release.

package/service/cadre-host.service.tmpl

@@ -0,0 +1,16 @@
+[Unit]
+Description=Sereus Cadre Host
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=@NODE_PATH@ @HOST_JS@ start --no-tui --data-dir @DATA_DIR@
+Restart=on-failure
+RestartPreventExitStatus=0
+RestartSec=5s
+Environment=NODE_ENV=production
+NoNewPrivileges=true
+
+[Install]
+WantedBy=default.target

package/service/com.serfab.cadre-host.plist.tmpl

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.serfab.cadre-host</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>@NODE_PATH@</string>
+    <string>@HOST_JS@</string>
+    <string>start</string>
+    <string>--no-tui</string>
+    <string>--data-dir</string>
+    <string>@DATA_DIR@</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+    <key>Crashed</key>
+    <true/>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>@DATA_DIR@/logs/out.log</string>
+  <key>StandardErrorPath</key>
+  <string>@DATA_DIR@/logs/err.log</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>NODE_ENV</key>
+    <string>production</string>
+  </dict>
+</dict>
+</plist>

package/service/install-service.ps1

@@ -0,0 +1,98 @@
+<#
+.SYNOPSIS
+  Install the Cadre Host as a Windows service using NSSM.
+
+.DESCRIPTION
+  Registers a Windows service named "CadreHost" that runs cadre-host via
+  NSSM. The service is configured so that exit code 0 is final (no
+  restart); non-zero exits trigger a 5-second-delayed restart, throttled
+  to 10 seconds.
+
+  NSSM (the Non-Sucking Service Manager) must be on PATH. Get it from
+  https://nssm.cc/download.
+
+.PARAMETER NodePath
+  Path to node.exe. Defaults to (Get-Command node).Source.
+
+.PARAMETER HostJs
+  Path to the cadre-host CLI entrypoint (dist/bin/host.js). Defaults to
+  the script's parent dir + dist\bin\host.js.
+
+.PARAMETER DataDir
+  Cadre host data directory (host.config.json + identity + state). Defaults
+  to $env:LocalAppData\CadreHost.
+#>
+
+[CmdletBinding()]
+param(
+  [string]$NodePath,
+  [string]$HostJs,
+  [string]$DataDir
+)
+
+$ErrorActionPreference = 'Stop'
+$ServiceName = 'CadreHost'
+
+$nssm = Get-Command nssm.exe -ErrorAction SilentlyContinue
+if (-not $nssm) {
+  Write-Error @"
+nssm.exe not found on PATH.
+Install NSSM from https://nssm.cc/download and either add it to PATH or
+copy nssm.exe to a directory on PATH. NSSM is required to host the
+Cadre Host as a Windows service.
+"@
+  exit 1
+}
+
+if (-not $NodePath) {
+  $node = Get-Command node.exe -ErrorAction SilentlyContinue
+  if (-not $node) {
+    Write-Error 'node.exe not found on PATH. Pass -NodePath explicitly.'
+    exit 1
+  }
+  $NodePath = $node.Source
+}
+
+if (-not $HostJs) {
+  $HostJs = (Resolve-Path (Join-Path $PSScriptRoot '..\dist\bin\host.js')).Path
+}
+
+if (-not (Test-Path $HostJs)) {
+  Write-Error "Cadre-host entry not found at $HostJs. Run 'yarn build' or set -HostJs."
+  exit 1
+}
+
+if (-not $DataDir) {
+  $DataDir = Join-Path $env:LocalAppData 'CadreHost'
+}
+
+$LogDir = Join-Path $DataDir 'logs'
+if (-not (Test-Path $LogDir)) {
+  New-Item -ItemType Directory -Path $LogDir -Force | Out-Null
+}
+
+# Remove any existing service so this script is idempotent.
+$existing = & nssm.exe status $ServiceName 2>$null
+if ($LASTEXITCODE -eq 0) {
+  Write-Host "Removing existing $ServiceName service..."
+  & nssm.exe stop   $ServiceName confirm | Out-Null
+  & nssm.exe remove $ServiceName confirm | Out-Null
+}
+
+Write-Host "Installing $ServiceName service..."
+
+# Use array-passed args so paths with spaces (e.g. "C:\Program Files\nodejs\node.exe")
+# are quoted correctly.
+$installArgs = @('install', $ServiceName, $NodePath, $HostJs, 'start', '--no-tui', '--data-dir', $DataDir)
+& nssm.exe @installArgs
+
+& nssm.exe set $ServiceName AppExit Default Restart
+& nssm.exe set $ServiceName AppExit 0       Exit
+& nssm.exe set $ServiceName AppRestartDelay 5000
+& nssm.exe set $ServiceName AppThrottle     10000
+& nssm.exe set $ServiceName AppStdout       (Join-Path $LogDir 'out.log')
+& nssm.exe set $ServiceName AppStderr       (Join-Path $LogDir 'err.log')
+& nssm.exe set $ServiceName AppRotateFiles  1
+& nssm.exe set $ServiceName Start           SERVICE_AUTO_START
+
+Write-Host "Service installed. Start it with: nssm start $ServiceName"

package/service/uninstall-service.ps1

@@ -0,0 +1,19 @@
+<#
+.SYNOPSIS
+  Uninstall the Cadre Host Windows service.
+#>
+
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+$ServiceName = 'CadreHost'
+
+$nssm = Get-Command nssm.exe -ErrorAction SilentlyContinue
+if (-not $nssm) {
+  Write-Error 'nssm.exe not found on PATH. Install NSSM from https://nssm.cc/download.'
+  exit 1
+}
+
+& nssm.exe stop   $ServiceName confirm 2>$null | Out-Null
+& nssm.exe remove $ServiceName confirm

package/src/__tests__/cli-invite.smoke.test.ts

@@ -0,0 +1,187 @@
+/**
+ * CLI smoke test for the `invite` subcommand. Spawns a stub HTTP server
+ * playing the role of cadre-host's management API and asserts the CLI:
+ *   - POSTs the expected body to /auth/invites
+ *   - Prints the encodedInvite on stdout
+ *   - Exits 0 on success / non-zero on connect failure
+ *
+ * Relies on `yarn build` having produced dist/bin/host.js.
+ */
+
+import { spawn } from 'node:child_process';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const binPath = resolve(here, '../../dist/bin/host.js');
+
+interface StubServer {
+  server: Server;
+  port: number;
+  requests: Array<{ method: string; url: string; body: string }>;
+  setResponse(handler: (req: IncomingMessage, res: ServerResponse) => void): void;
+}
+
+async function startStub(): Promise<StubServer> {
+  const requests: StubServer['requests'] = [];
+  let handler: (req: IncomingMessage, res: ServerResponse) => void = (_req, res) => {
+    res.statusCode = 200;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify({
+      encodedInvite: 'fake-encoded-invite',
+      token: 'fake-token',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    }));
+  };
+
+  const server = createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => {
+      requests.push({ method: req.method ?? '', url: req.url ?? '', body: Buffer.concat(chunks).toString('utf8') });
+      handler(req, res);
+    });
+  });
+
+  await new Promise<void>((resolveStart) => server.listen(0, '127.0.0.1', () => resolveStart()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return {
+    server,
+    port,
+    requests,
+    setResponse: (h) => { handler = h; },
+  };
+}
+
+function runCli(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolveRun) => {
+    const child = spawn(process.execPath, [binPath, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8'); });
+    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8'); });
+    child.on('close', (code) => resolveRun({ code: code ?? -1, stdout, stderr }));
+  });
+}
+
+let stub: StubServer;
+
+beforeEach(async () => {
+  if (!existsSync(binPath)) {
+    throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
+  }
+  stub = await startStub();
+});
+
+afterEach(async () => {
+  await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
+});
+
+describe('cadre-host invite CLI', () => {
+  it('POSTs to /auth/invites with label + ttlMs and prints encoded invite', async () => {
+    const result = await runCli(['invite', "Mom's phone", '--ttl', '12h', '--port', String(stub.port)]);
+
+    expect(result.code).toBe(0);
+    expect(result.stdout.trim()).toBe('fake-encoded-invite');
+    expect(stub.requests).toHaveLength(1);
+    expect(stub.requests[0]!.method).toBe('POST');
+    expect(stub.requests[0]!.url).toBe('/auth/invites');
+    const body = JSON.parse(stub.requests[0]!.body);
+    expect(body.label).toBe("Mom's phone");
+    expect(body.ttlMs).toBe(12 * 60 * 60 * 1000);
+  });
+
+  it('exits non-zero when cadre-host returns an error', async () => {
+    stub.setResponse((_req, res) => {
+      res.statusCode = 500;
+      res.end('boom');
+    });
+    const result = await runCli(['invite', 'Test', '--port', String(stub.port)]);
+    expect(result.code).not.toBe(0);
+    expect(result.stderr).toContain('500');
+  });
+
+  it('exits 2 (no service) when cadre-host is not reachable', async () => {
+    // Use a port the stub server occupied; close it first so connections fail.
+    const port = stub.port;
+    await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
+    const result = await runCli(['invite', 'Test', '--port', String(port)]);
+    expect(result.code).toBe(2);
+    expect(result.stderr).toMatch(/cadre-host start|Failed to reach/);
+  });
+
+  it('rejects invalid --ttl', async () => {
+    const result = await runCli(['invite', 'Test', '--ttl', 'eternity', '--port', String(stub.port)]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/Invalid --ttl/);
+  });
+});
+
+describe('cadre-host trust list CLI', () => {
+  it('renders members and pending invites', async () => {
+    stub.setResponse((_req, res) => {
+      res.statusCode = 200;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({
+        members: [
+          { peerId: '12D3KooWAlice', label: 'Alice', addedAt: 't1' },
+          { peerId: '12D3KooWHost', label: 'Host', addedAt: 't2', self: true },
+        ],
+        pending: [
+          { token: 'tok1', label: 'Mom', createdAt: 't3', expiresAt: 't4' },
+        ],
+      }));
+    });
+
+    const result = await runCli(['trust', 'list', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('12D3KooWAlice');
+    expect(result.stdout).toContain('Alice');
+    expect(result.stdout).toContain('[self]');
+    expect(result.stdout).toContain('tok1');
+    expect(result.stdout).toContain('Mom');
+  });
+});
+
+describe('cadre-host trust revoke CLI', () => {
+  it('DELETEs /auth/invites/<token> by default', async () => {
+    stub.setResponse((_req, res) => {
+      res.statusCode = 204;
+      res.end();
+    });
+    const result = await runCli(['trust', 'revoke', 'some-token', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.method).toBe('DELETE');
+    expect(stub.requests[0]!.url).toBe('/auth/invites/some-token');
+  });
+
+  it('DELETEs /auth/members/<peerId> when id looks like a peerId', async () => {
+    stub.setResponse((_req, res) => {
+      res.statusCode = 204;
+      res.end();
+    });
+    const result = await runCli(['trust', 'revoke', '12D3KooWAlice', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.url).toBe('/auth/members/12D3KooWAlice');
+  });
+
+  it('treats secp256k1 peer IDs (16Uiu2HAm…) as members', async () => {
+    stub.setResponse((_req, res) => {
+      res.statusCode = 204;
+      res.end();
+    });
+    const result = await runCli(['trust', 'revoke', '16Uiu2HAmExample', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.url).toBe('/auth/members/16Uiu2HAmExample');
+  });
+
+  it('rejects invalid --port', async () => {
+    const result = await runCli(['trust', 'revoke', 'some-token', '--port', 'garbage']);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/Invalid --port/);
+  });
+});

package/src/__tests__/cli-nat.smoke.test.ts

@@ -0,0 +1,207 @@
+/**
+ * CLI smoke test for the `nat` subcommand. Spawns a stub HTTP server playing
+ * the role of cadre-host's management API and asserts the CLI:
+ *   - GETs /nat/status
+ *   - POSTs /nat/test
+ *   - PUTs /nat/ddns with the expected body
+ *   - PUTs /nat/settings
+ *   - Exits non-zero when the host is not reachable
+ *
+ * Relies on `yarn build` having produced dist/bin/host.js.
+ */
+
+import { spawn } from 'node:child_process';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const binPath = resolve(here, '../../dist/bin/host.js');
+
+interface StubServer {
+  server: Server;
+  port: number;
+  requests: Array<{ method: string; url: string; body: string }>;
+  setResponse(handler: (req: IncomingMessage, res: ServerResponse) => void): void;
+}
+
+const DEFAULT_STATUS = {
+  portMode: 'auto-upnp',
+  externalPort: 4001,
+  internalPort: 4001,
+  routerExternalIp: '203.0.113.5',
+  mappingLeaseExpiresAt: null,
+  externalIp: '203.0.113.5',
+  externalIpDetectedAt: new Date().toISOString(),
+  cgnatDetected: false,
+  directReachability: 'reachable',
+  lastTestedAt: null,
+  ddns: {
+    providerId: 'duckdns',
+    hostname: 'foo.duckdns.org',
+    externallyManaged: false,
+    lastUpdateAt: null,
+    lastUpdateOk: null,
+    lastError: null,
+  },
+};
+
+async function startStub(): Promise<StubServer> {
+  const requests: StubServer['requests'] = [];
+  let handler: (req: IncomingMessage, res: ServerResponse) => void = (_req, res) => {
+    res.statusCode = 200;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify(DEFAULT_STATUS));
+  };
+
+  const server = createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => {
+      requests.push({ method: req.method ?? '', url: req.url ?? '', body: Buffer.concat(chunks).toString('utf8') });
+      handler(req, res);
+    });
+  });
+
+  await new Promise<void>((resolveStart) => server.listen(0, '127.0.0.1', () => resolveStart()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return {
+    server,
+    port,
+    requests,
+    setResponse: (h) => { handler = h; },
+  };
+}
+
+function runCli(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolveRun) => {
+    const child = spawn(process.execPath, [binPath, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8'); });
+    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8'); });
+    child.on('close', (code) => resolveRun({ code: code ?? -1, stdout, stderr }));
+  });
+}
+
+let stub: StubServer;
+
+beforeEach(async () => {
+  if (!existsSync(binPath)) {
+    throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
+  }
+  stub = await startStub();
+});
+
+afterEach(async () => {
+  await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
+});
+
+describe('cadre-host nat status', () => {
+  it('GETs /nat/status and renders the snapshot', async () => {
+    const result = await runCli(['nat', 'status', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(stub.requests).toHaveLength(1);
+    expect(stub.requests[0]!.method).toBe('GET');
+    expect(stub.requests[0]!.url).toBe('/nat/status');
+    expect(result.stdout).toContain('auto-upnp');
+    expect(result.stdout).toContain('203.0.113.5');
+    expect(result.stdout).toContain('foo.duckdns.org');
+  });
+
+  it('--json prints raw JSON', async () => {
+    const result = await runCli(['nat', 'status', '--port', String(stub.port), '--json']);
+    expect(result.code).toBe(0);
+    const parsed = JSON.parse(result.stdout);
+    expect(parsed.portMode).toBe('auto-upnp');
+  });
+
+  it('exits 2 when cadre-host is unreachable', async () => {
+    const port = stub.port;
+    await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
+    const result = await runCli(['nat', 'status', '--port', String(port)]);
+    expect(result.code).toBe(2);
+    expect(result.stderr).toMatch(/cadre-host start|Failed to reach/);
+  });
+});
+
+describe('cadre-host nat test', () => {
+  it('POSTs /nat/test', async () => {
+    const result = await runCli(['nat', 'test', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.method).toBe('POST');
+    expect(stub.requests[0]!.url).toBe('/nat/test');
+  });
+});
+
+describe('cadre-host nat ddns set', () => {
+  it('PUTs /nat/ddns with provider + hostname + token', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'set', 'duckdns',
+      '--hostname', 'foo.duckdns.org',
+      '--token', 'TOK',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.method).toBe('PUT');
+    expect(stub.requests[0]!.url).toBe('/nat/ddns');
+    const body = JSON.parse(stub.requests[0]!.body);
+    expect(body.providerId).toBe('duckdns');
+    expect(body.hostname).toBe('foo.duckdns.org');
+    expect(body.config).toEqual({ token: 'TOK' });
+  });
+
+  it('exits 1 when --hostname is missing', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'set', 'duckdns',
+      '--token', 'TOK',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/--hostname/);
+  });
+
+  it('exits 1 when --token is missing on a non-TTY stdin', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'set', 'duckdns',
+      '--hostname', 'foo.duckdns.org',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/--token/);
+  });
+});
+
+describe('cadre-host nat ddns external', () => {
+  it('PUTs /nat/settings with externallyManaged=true', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'external',
+      '--hostname', 'mydomain.example.com',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.method).toBe('PUT');
+    expect(stub.requests[0]!.url).toBe('/nat/settings');
+    const body = JSON.parse(stub.requests[0]!.body);
+    expect(body.ddns.hostname).toBe('mydomain.example.com');
+    expect(body.ddns.externallyManaged).toBe(true);
+  });
+});
+
+describe('cadre-host nat settings', () => {
+  it('PUTs /nat/settings with --external-port and --no-upnp', async () => {
+    const result = await runCli([
+      'nat', 'settings',
+      '--external-port', '4002',
+      '--no-upnp',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(0);
+    const body = JSON.parse(stub.requests[0]!.body);
+    expect(body.externalPort).toBe(4002);
+    expect(body.upnpEnabled).toBe(false);
+  });
+});