@serfab/cadre-host 1.14.0 → 1.15.0

package/src/bin/host.ts

@@ -18,12 +18,13 @@
  */
 
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
 
 import { Command, InvalidArgumentError } from 'commander';
 
 import { Installer } from '../installer/index.js';
+import { packageVersion } from '../package-version.js';
 import { readHostConfig, updateHostConfig } from '../installer/config.js';
 import {
   configPath as resolveConfigPath,
@@ -42,7 +43,7 @@ import {
   HOSTED_NODE_REAP_SWEEP_MS,
   HOSTED_NODE_SPAWNING_TTL_MS,
 } from '../hosted/index.js';
-import { NatService } from '../nat/index.js';
+import { effectiveNetworkMode, NatService, NatStore, publicInterfaceAddress } from '../nat/index.js';
 import type { ManualForwardPatch } from '../nat/types.js';
 import { createSecretsStore } from '../nat/secrets/index.js';
 import {
@@ -55,6 +56,7 @@ import {
 import { createLocalUiServer, HostSettingsStore } from '../server/index.js';
 import { openBrowser } from '../installer/browser.js';
 import { printForwardResult, printNatStatus, type NatStatusLike } from './nat-output.js';
+import { isHeadless, uiAccessLines } from './ui-access.js';
 import {
   printClaimPayload,
   printClaimed,
@@ -80,7 +82,7 @@ const program = new Command();
 program
   .name('cadre-host')
   .description('Sereus cadre node manager for self-hosted basement-PC deployments')
-  .version(readPackageVersion());
+  .version(packageVersion);
 
 // ============================================================================
 // install — run the first-run wizard + register the system service
@@ -114,7 +116,8 @@ program
         ...(opts.dataDir ? { dataDir: opts.dataDir } : {}),
         ...(typeof opts.uiPort === 'number' ? { uiPort: opts.uiPort } : {}),
         noUpnp: opts.upnp === false,
-        openBrowser: opts.browser !== false,
+        // Headless, a browser would open nowhere the admin can see; the `ssh -L` lines below say how instead.
+        openBrowser: opts.browser !== false && !isHeadless(),
         system: Boolean(opts.system),
         ...(opts.nodePath ? { nodePath: opts.nodePath } : {}),
         noService: opts.service === false,
@@ -128,6 +131,15 @@ program
         console.log('  Service:      not registered (--no-service)');
         console.log(`  Run the host: cadre-host start --data-dir "${result.dataDir}"`);
       }
+      // A re-install keeps the `network` setting an earlier one recorded in nat.json.
+      const publicIp = publicInterfaceAddress();
+      const mode = effectiveNetworkMode(new NatStore(result.dataDir).load().network, publicIp);
+      console.log(mode === 'public'
+        ? `  Network:      public IP${publicIp ? ` ${publicIp}` : ''}: nodes are reached directly. Allow their ports through your firewall (the UI lists them).`
+        : '  Network:      behind a router: nodes need UPnP or a port forward (the UI shows which).');
+      console.log('');
+      for (const line of uiAccessLines(Number(new URL(result.uiUrl).port), isHeadless())) console.log(line);
+      console.log('Everything else (a public name, joining a cadre, ports) is in the UI.');
       process.exit(0);
     } catch (err) {
       console.error(`install failed: ${(err as Error).message}`);
@@ -233,7 +245,7 @@ program
       const serviceHost = createServiceHost(platform);
       const updateService = new UpdateService({
         dataDir: cfg.dataDir,
-        currentVersion: readPackageVersion(),
+        currentVersion: packageVersion,
         settings: cfg.updates,
         ...(cfg.updates.manifestUrl ? { manifestUrl: cfg.updates.manifestUrl } : {}),
         restart: async () => {
@@ -304,6 +316,8 @@ program
         orchestrator,
         store: hostedNodeStore,
         addresses: natService,
+        // Re-read per claim code so a Settings edit (or a hand edit) applies to the next code shown.
+        claimAddressSettings: () => readHostConfig(cfgPath).claimAddresses,
       });
 
       // Respawn supervision — nothing else brings a hosted node back. A crash,
@@ -389,6 +403,12 @@ program
       }
       const cfg = readHostConfig(cfgPath);
       const url = `http://127.0.0.1:${cfg.uiPort}`;
+      if (isHeadless()) {
+        // A browser here would open nowhere the admin can see: say how to reach it instead.
+        for (const line of uiAccessLines(cfg.uiPort, true)) console.log(line);
+        process.exit(0);
+        return;
+      }
       console.log(url);
       if (opts.browser !== false) {
         const res = openBrowser(url);
@@ -413,19 +433,6 @@ function parseIntArg(raw: string): number {
   return n;
 }
 
-function readPackageVersion(): string {
-  try {
-    // dist/bin/host.js -> ../../package.json
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkgPath = resolve(here, '..', '..', 'package.json');
-    const raw = readFileSync(pkgPath, 'utf8');
-    const parsed = JSON.parse(raw) as { version?: string };
-    return parsed.version ?? '0.0.0-unknown';
-  } catch {
-    return '0.0.0-unknown';
-  }
-}
-
 function waitForTermination(): Promise<void> {
   return new Promise<void>((resolveTerm) => {
     const done = () => resolveTerm();
@@ -673,18 +680,21 @@ nat
 
 nat
   .command('settings')
-  .description('Update NAT settings (UPnP toggle)')
+  .description('Update NAT settings (network mode, UPnP toggle)')
+  .option('--network <mode>', 'auto (default: public when this machine holds a public IPv4), lan (behind a router) or public (reached directly, e.g. a VPS)')
   .option('--upnp', 'Ask the router for port mappings over UPnP')
   .option('--no-upnp', 'Stop asking the router for port mappings (manual forwards stay)')
   .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
   .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
   .action(async (opts: {
+    network?: string;
     upnp?: boolean;
     port: string;
     host: string;
   }) => {
     const url = `http://${opts.host}:${resolvePort(opts.port)}/nat/settings`;
     const patch: Record<string, unknown> = {};
+    if (opts.network !== undefined) patch.network = opts.network;
     // Commander assigns `upnp: false` when `--no-upnp` is passed.
     if (opts.upnp === false) patch.upnpEnabled = false;
     if (opts.upnp === true) patch.upnpEnabled = true;

package/src/bin/nat-output.ts

@@ -26,6 +26,7 @@ export interface NatNodeLike {
 }
 
 export interface NatStatusLike {
+  network?: { setting?: string; mode?: string; publicInterfaceIp?: string | null };
   upnpEnabled?: boolean;
   gateway?: {
     found?: boolean;
@@ -85,6 +86,15 @@ export function printForwardResult(nodeId: string, s: NatStatusLike): void {
 }
 
 function printHostLines(s: NatStatusLike): void {
+  const network = s.network ?? {};
+  const how = network.setting === 'auto' || network.setting === undefined ? 'detected' : 'set';
+  if (network.mode === 'public') {
+    console.log(`Network:      public IP ${network.publicInterfaceIp ?? s.externalIp ?? '?'} on this machine (${how}); no router, so no UPnP`);
+    console.log(`External IP:  ${s.externalIp ?? network.publicInterfaceIp ?? '(unknown)'}`);
+    console.log(`Reachability: ${s.directReachability ?? 'unknown'}${s.lastTestedAt ? `  (tested ${s.lastTestedAt})` : ''}`);
+    return;
+  }
+  console.log(`Network:      behind a router (${how})`);
   const gateway = s.gateway ?? {};
   const gatewayLine = gateway.found
     ? `found (this machine is ${gateway.lanAddress ?? '?'} on its network)`
@@ -115,7 +125,7 @@ function printNodeReachability(n: NatNodeLike, s: NatStatusLike): void {
   printField('TCP', [formatRoute(n.tcp)]);
   printField('WebSocket', [n.ws ? formatRoute(n.ws) : 'not available']);
   printField('Public', n.publicAddrs?.length ? n.publicAddrs : ['none']);
-  if (n.reason) printField('Why', [n.reason]);
+  if (n.reason) printField(n.verdict === 'direct' ? 'Firewall' : 'Why', [n.reason]);
   const advice = forwardAdvice(n, s);
   if (advice.length > 0) printField('To fix', advice);
 }
@@ -129,6 +139,7 @@ function formatRoute(r: NatPortRouteLike | undefined): string {
   const internal = `internal ${r.internalPort ?? '?'}`;
   if (r.externalPort == null) return `${internal} → not mapped${r.error ? ` (${r.error})` : ''}`;
   const failed = r.error ? `; last attempt failed: ${r.error}` : '';
+  if (r.source === 'direct') return `${internal} → public, as-is${failed}`;
   return `${internal} → external ${r.externalPort} (${r.source === 'manual' ? 'forwarded by hand' : 'UPnP'}${failed})`;
 }
 

package/src/bin/ui-access.ts

@@ -0,0 +1,50 @@
+/**
+ * How to reach the local UI from where the admin is sitting. On a machine with a desktop, open
+ * the URL; over SSH or on a headless server, forward the port from the admin's own computer
+ * first. The UI binds 127.0.0.1 only and checks the Host header, so the local port must equal
+ * the remote one.
+ */
+
+import { hostname, userInfo } from 'node:os';
+
+/** Over SSH, or Linux with no display server: a browser here would show nothing to the admin. */
+export function isHeadless(platform: NodeJS.Platform = process.platform, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.SSH_CONNECTION || env.SSH_TTY) return true;
+  return platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+
+/** Who to SSH in as, and where; `sshPort` only when it is not 22. */
+export interface SshLogin {
+  user: string;
+  host: string;
+  sshPort?: number;
+}
+
+/** The lines telling the admin how to open the UI at `port`. */
+export function uiAccessLines(port: number, headless: boolean, who: SshLogin = currentLogin()): string[] {
+  const url = `http://127.0.0.1:${port}`;
+  if (!headless) return [`Open the UI: ${url}`];
+  const portFlag = who.sshPort !== undefined && who.sshPort !== 22 ? ` -p ${who.sshPort}` : '';
+  return [
+    'Open the UI from your own computer (this session has no screen):',
+    `  ssh${portFlag} -L ${port}:127.0.0.1:${port} ${who.user}@${who.host}`,
+    `  then browse to ${url}`,
+  ];
+}
+
+/**
+ * Over SSH, the server address and port the admin's client connected to (`SSH_CONNECTION` is
+ * "client-ip client-port server-ip server-port"): a VPS's hostname rarely resolves from the
+ * admin's computer, the address they just reached does. Otherwise this machine's hostname.
+ */
+export function currentLogin(env: NodeJS.ProcessEnv = process.env): SshLogin {
+  let user = '<you>';
+  try {
+    user = userInfo().username;
+  } catch {
+    // no passwd entry (some containers): keep the placeholder
+  }
+  const [, , serverIp, serverPort] = (env.SSH_CONNECTION ?? '').trim().split(/\s+/);
+  if (serverIp && serverPort) return { user, host: serverIp, sshPort: Number(serverPort) };
+  return { user, host: hostname() };
+}

package/src/hosted/__tests__/fake-orchestrator.test.ts

@@ -23,7 +23,6 @@ import { FakeOrchestrator } from './fake-orchestrator.js';
 const request = (containerId: string): HostedSpawnRequest => ({
   containerId,
   partyId: 'party-P',
-  bootstrapNodes: ['/ip4/127.0.0.1/tcp/4001/p2p/12D3KooWA9hbnKrRnPRSPTRkzXqTHzGE8YpJ3JHZmQ5tGwLRTMmp'],
   profile: 'storage',
 });