@serfab/cadre-host 1.13.0 → 1.15.0

package/src/nat/reachability.ts

@@ -1,34 +1,155 @@
-import type { DirectReachability, PortForwardMode } from './types.js';
-
-export interface ReachabilityInput {
-  portMode: PortForwardMode;
-  cgnatDetected: boolean;
-}
-
-/**
- * v1 reachability heuristic.
- *
- * Returns:
- *   - 'cgnat' when CGNAT was detected (highest signal — UPnP succeeded but our
- *     external IP isn't actually reachable from the open internet).
- *   - 'unreachable' when port mapping failed.
- *   - 'reachable' when an auto mapping succeeded.
- *   - 'unknown' otherwise (manual config, disabled UPnP, etc).
- *
- * A future ticket will replace this with libp2p AutoNAT or a sereus-owned
- * dial-back probe (see the follow-up section of `6.3-cadre-host-nat`).
- */
-export function evaluateReachability(input: ReachabilityInput): DirectReachability {
-  if (input.cgnatDetected) return 'cgnat';
-  switch (input.portMode) {
-    case 'auto-upnp':
-    case 'auto-natpmp':
-      return 'reachable';
-    case 'failed':
-      return 'unreachable';
-    case 'manual':
-    case 'disabled':
-    default:
-      return 'unknown';
-  }
-}
+/**
+ * Reachability verdicts: one per hosted node, and the host-level roll-up the
+ * dashboard badge shows. Heuristics over the mapping table, not a dial-back —
+ * libp2p AutoNAT is a later ticket.
+ */
+
+import type {
+  DirectReachability,
+  NodeReachability,
+  NodeVerdict,
+  PortKind,
+  PortRoute,
+} from './types.js';
+
+export interface NodeVerdictInput {
+  tcp: PortRoute;
+  /** Null for a handle persisted by an older build without a WebSocket port. */
+  ws: PortRoute | null;
+  /** Whether a public host part exists: a DDNS hostname, or a public IPv4. */
+  hostKnown: boolean;
+  cgnatDetected: boolean;
+  upnpEnabled: boolean;
+  gatewayFound: boolean;
+  /** The address a user forwards to; null when no gateway was found. */
+  lanAddress: string | null;
+}
+
+export interface NodeVerdictResult {
+  verdict: NodeVerdict;
+  reason: string | null;
+}
+
+/**
+ * `unreachable` when either port has no usable route or the host part is
+ * unknown; otherwise `manual` when either port is forwarded by hand, `direct`
+ * when the ports are reached as-is (public mode, with the firewall reminder as
+ * the reason), else `mapped`. A UPnP route under CGNAT is not usable: the
+ * router's mapping is on a carrier-private address.
+ */
+export function evaluateNodeReachability(input: NodeVerdictInput): NodeVerdictResult {
+  const ports = portRoutes(input);
+  const failing = ports.filter(({ route }) => !usable(route, input.cgnatDetected));
+  if (!input.hostKnown) {
+    return { verdict: 'unreachable', reason: HOST_UNKNOWN_REASON };
+  }
+  if (failing.length > 0) {
+    return { verdict: 'unreachable', reason: describeFailures(failing, input) };
+  }
+  if (ports.some(({ route }) => route.source === 'manual')) return { verdict: 'manual', reason: null };
+  if (ports.some(({ route }) => route.source === 'direct')) return { verdict: 'direct', reason: firewallReminder(ports) };
+  return { verdict: 'mapped', reason: null };
+}
+
+/**
+ * Host roll-up: `cgnat` when CGNAT is detected and no node is reachable
+ * through a manual route; `unknown` with no running nodes; `reachable` when
+ * every running node is `mapped`/`manual`/`direct`; else `unreachable`.
+ */
+export function evaluateHostReachability(
+  nodes: ReadonlyArray<Pick<NodeReachability, 'running' | 'verdict'>>,
+  cgnatDetected: boolean,
+): DirectReachability {
+  const running = nodes.filter((n) => n.running);
+  if (cgnatDetected && !running.some((n) => n.verdict === 'manual')) return 'cgnat';
+  if (running.length === 0) return 'unknown';
+  return running.every((n) => n.verdict !== 'unreachable') ? 'reachable' : 'unreachable';
+}
+
+const HOST_UNKNOWN_REASON =
+  "This host's public address is unknown: no dynamic DNS hostname is set and no public IPv4 address was detected. " +
+  'Set a DDNS hostname, or check that this machine can reach the internet.';
+
+interface PortEntry {
+  kind: PortKind;
+  route: PortRoute;
+}
+
+function portRoutes(input: NodeVerdictInput): PortEntry[] {
+  const out: PortEntry[] = [{ kind: 'tcp', route: input.tcp }];
+  if (input.ws) out.push({ kind: 'ws', route: input.ws });
+  return out;
+}
+
+function usable(route: PortRoute, cgnatDetected: boolean): boolean {
+  if (route.externalPort === null || route.source === null) return false;
+  return !(cgnatDetected && route.source === 'upnp');
+}
+
+type FailureCause = 'cgnat' | 'refused' | 'upnp_off' | 'no_gateway' | 'pending';
+
+/** Behind CGNAT no router-side remedy helps, so CGNAT outranks whatever else failed the port. */
+function causeOf(route: PortRoute, input: NodeVerdictInput): FailureCause {
+  if (input.cgnatDetected) return 'cgnat';
+  if (route.error) return 'refused';
+  if (!input.upnpEnabled) return 'upnp_off';
+  if (!input.gatewayFound) return 'no_gateway';
+  return 'pending';
+}
+
+/** One sentence per distinct cause, each naming every port that failed for it. */
+function describeFailures(failing: PortEntry[], input: NodeVerdictInput): string {
+  const byCause = new Map<FailureCause, PortEntry[]>();
+  for (const entry of failing) {
+    const cause = causeOf(entry.route, input);
+    byCause.set(cause, [...(byCause.get(cause) ?? []), entry]);
+  }
+  return [...byCause.entries()].map(([cause, entries]) => describeCause(cause, entries, input)).join(' ');
+}
+
+function describeCause(cause: FailureCause, entries: PortEntry[], input: NodeVerdictInput): string {
+  const names = entries.map(({ kind, route }) => `${kindLabel(kind)} port ${route.internalPort}`);
+  const lan = input.lanAddress ?? "this machine's LAN address";
+  const forwardHint = `Forward ${entries.length === 1 ? 'port' : 'ports'} ${listPorts(entries)} to ${lan} on your router, then tell cadre-host the external ${entries.length === 1 ? 'port' : 'ports'}.`;
+  switch (cause) {
+    case 'cgnat':
+      return `This host is behind carrier-grade NAT, so the ${joinNames(names)} cannot be reached from outside through your router, and neither UPnP nor a port forward on your router will help; a relay is needed.`;
+    case 'refused': {
+      const errors = entries.map(({ route }) => route.error).filter((e): e is string => !!e);
+      return `Router refused the ${joinNames(names)} mapping (${errors.join('; ')}). ${forwardHint}`;
+    }
+    case 'upnp_off':
+      return `UPnP is off, so the ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped. Turn UPnP on, or: ${lowerFirst(forwardHint)}`;
+    case 'no_gateway':
+      return `No UPnP router answered, so the ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped. Enable UPnP on your router, or: ${lowerFirst(forwardHint)}`;
+    case 'pending':
+      return `The ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped yet; the router is being asked.`;
+  }
+}
+
+/** Public mode: nothing to map, but a host or cloud firewall can still block the ports. */
+function firewallReminder(ports: PortEntry[]): string {
+  const numbers = ports.map(({ route }) => route.internalPort);
+  const ufw = numbers.length === 2 && Math.abs(numbers[0]! - numbers[1]!) === 1
+    ? `${Math.min(...numbers)}:${Math.max(...numbers)}/tcp`
+    : `${numbers.join(',')}/tcp`;
+  return `Reached directly at this machine's public address. Allow TCP ${ports.length === 1 ? 'port' : 'ports'} ${listPorts(ports)} through any firewall `
+    + `(for example: sudo ufw allow ${ufw}; and any cloud-provider firewall).`;
+}
+
+function kindLabel(kind: PortKind): string {
+  return kind === 'tcp' ? 'TCP' : 'WebSocket';
+}
+
+function listPorts(entries: PortEntry[]): string {
+  return joinNames(entries.map(({ route }) => String(route.internalPort)));
+}
+
+function joinNames(names: string[]): string {
+  if (names.length <= 1) return names[0] ?? '';
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+
+function lowerFirst(s: string): string {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}

package/src/nat/types.ts

@@ -1,52 +1,113 @@
 /**
  * NAT/DDNS types for cadre-host.
  *
- * cadre-host runs on home/SMB machines that are typically behind NAT. To be
- * dialable from the open internet the host must:
- *   1. Punch a port forward on the upstream router (UPnP/NAT-PMP).
+ * cadre-host runs on home/SMB machines that are typically behind NAT. For the
+ * nodes it runs to be dialable from the open internet the host must:
+ *   1. Map every hosted node's two libp2p ports (TCP, and the WebSocket port a
+ *      phone dials) through the upstream router, or let the user forward them
+ *      by hand.
  *   2. Detect its external IP (and whether it's behind CGNAT).
  *   3. Optionally publish a stable hostname via dynamic DNS.
  *
- * State for these three concerns lives in `<rootDir>/nat.json` (user settings)
- * and is exposed as a single `NatStatusSnapshot` to the management UI.
+ * State for these concerns lives in `<rootDir>/nat.json` (user settings) and is
+ * exposed as a single `NatStatusSnapshot` to the management UI, with one
+ * `NodeReachability` entry per hosted node.
  *
  * Credentials for DDNS providers are NOT stored in `nat.json`. They go through
  * the SecretsStore (keytar, with a 0600 file fallback).
  */
 
-/** Port-forwarding mode currently in effect. */
-export type PortForwardMode =
-  | 'auto-upnp'
-  | 'auto-natpmp'
-  | 'manual'
-  | 'failed'
-  | 'disabled';
-
-/** Reachability verdict — best-effort heuristic until AutoNAT lands. */
+/** Reachability roll-up across the host's running nodes — see `reachability.ts`. */
 export type DirectReachability = 'reachable' | 'unreachable' | 'unknown' | 'cgnat';
 
-/** Snapshot returned to the management UI / CLI. */
-export interface NatStatusSnapshot {
-  // Port forwarding
-  portMode: PortForwardMode;
-  externalPort: number;
+/** The two ports of a hosted node that are mapped: libp2p TCP and libp2p WebSocket. */
+export type PortKind = 'tcp' | 'ws';
+
+/**
+ * How this machine meets the internet. `lan`: behind a router (home or office), so node ports need
+ * UPnP or a forward on the router. `public`: an interface holds a public IPv4 (a VPS, a server with a
+ * routed address), so node ports are reachable at their own numbers unless a firewall blocks them.
+ */
+export type NetworkMode = 'lan' | 'public';
+
+/** The `network` setting: `auto` picks the mode from this machine's interfaces. */
+export type NetworkSetting = 'auto' | NetworkMode;
+
+/** The network section of the status snapshot. */
+export interface NatNetworkStatus {
+  setting: NetworkSetting;
+  /** The mode in effect: the setting, or what `auto` found. */
+  mode: NetworkMode;
+  /** The public IPv4 an interface holds, when one does; what `auto` decides on. */
+  publicInterfaceIp: string | null;
+}
+
+/** Where a port's external route came from. `direct`: public mode, the port as-is. */
+export type PortRouteSource = 'upnp' | 'manual' | 'direct';
+
+/** How one of a node's ports is reached from outside the home network. */
+export interface PortRoute {
   internalPort: number;
-  /** IP the router reports as its WAN address. Null when not auto-mapped. */
+  /** Port reachable from outside; null when there is no route. */
+  externalPort: number | null;
+  source: PortRouteSource | null;
+  /** ISO timestamp when the router lease expires; UPnP routes only. */
+  leaseExpiresAt: string | null;
+  /** Last mapping failure, in plain language; null when the last attempt succeeded. */
+  error: string | null;
+}
+
+/** Per-node verdict. `direct`: reachable at this machine's public address, firewall permitting. */
+export type NodeVerdict = 'mapped' | 'manual' | 'direct' | 'unreachable';
+
+/** Reachability of one hosted node, as reported in the status snapshot. */
+export interface NodeReachability {
+  nodeId: string;
+  /** Whether the node's process is running; a stopped node keeps its last routes until the unmap grace elapses. */
+  running: boolean;
+  verdict: NodeVerdict;
+  /**
+   * Plain-language reason and remedy when unreachable, e.g. "Router refused
+   * the WebSocket port mapping. Forward port 10004 to 192.168.1.20 on your
+   * router, then tell cadre-host the external port." For `direct`, the
+   * firewall reminder: which ports to allow.
+   */
+  reason: string | null;
+  tcp: PortRoute;
+  /** Null for a handle persisted by an older build without a WebSocket port. */
+  ws: PortRoute | null;
+  /** Multiaddrs (no `/p2p/` suffix) through which the node is reachable from outside. */
+  publicAddrs: string[];
+}
+
+/** The UPnP gateway as the host last saw it. */
+export interface NatGatewayStatus {
+  found: boolean;
+  /** This machine's address on the router's subnet — the address a user forwards to. */
+  lanAddress: string | null;
+  /** The WAN address the router reports for itself. */
   routerExternalIp: string | null;
-  /** ISO timestamp when the current mapping lease expires. */
-  mappingLeaseExpiresAt: string | null;
+  /** Why discovery or the last gateway operation failed; null when it did not. */
+  lastError: string | null;
+}
+
+/** Snapshot returned to the management UI / CLI. */
+export interface NatStatusSnapshot {
+  network: NatNetworkStatus;
+  upnpEnabled: boolean;
+  gateway: NatGatewayStatus;
 
-  // External IP (from public probe; may differ from routerExternalIp under CGNAT)
+  // External IP (from the public probe, falling back to the router's report).
   externalIp: string | null;
   externalIpDetectedAt: string | null;
   cgnatDetected: boolean;
 
-  // Reachability verdict
+  /** Roll-up across running nodes; see `reachability.ts`. */
   directReachability: DirectReachability;
   lastTestedAt: string | null;
 
-  // DDNS
   ddns: NatDdnsStatus;
+  nodes: NodeReachability[];
 }
 
 /** DDNS sub-section of the status snapshot. */
@@ -65,18 +126,30 @@ export interface NatDdnsStatus {
   lastError: string | null;
 }
 
+/** The external ports a user forwarded on their router for one node, per port kind. */
+export interface ManualForward {
+  tcp?: number;
+  ws?: number;
+}
+
+/** Patch applied by `PUT /nat/nodes/:nodeId/forward`: `null` clears that port. */
+export interface ManualForwardPatch {
+  tcp?: number | null;
+  ws?: number | null;
+}
+
 /**
  * On-disk shape of `nat.json`. NEVER contains DDNS credentials — those live
  * in the SecretsStore.
  */
 export interface NatSettingsFile {
   version: 1;
-  /** External port to map (and announce). Default 4001. */
-  externalPort: number;
-  /** Internal libp2p port. Default 4001. */
-  internalPort: number;
-  /** Whether to attempt UPnP/NAT-PMP at all. */
+  /** LAN or public-IP mode; `auto` (default) decides from the interfaces. Absent in older files. */
+  network: NetworkSetting;
+  /** Whether to ask the router for port mappings at all. Ignored in public mode. */
   upnpEnabled: boolean;
+  /** Per node id: the external port the user forwarded on their router, per port kind. */
+  forwards: Record<string, ManualForward>;
   ddns: NatDdnsSettings;
 }
 
@@ -107,8 +180,8 @@ export type NatErrorCode =
   | 'secrets_unavailable'
   | 'storage_error'
   | 'invalid_config'
-  /** The owner node's admin channel is unreachable / not ready. */
-  | 'node_unavailable';
+  /** A manual forward named a node id the host does not run. */
+  | 'unknown_node';
 
 /** Typed error carrying a stable `code` for HTTP mapping in the local-ui. */
 export class NatError extends Error {
@@ -139,11 +212,10 @@ export interface DdnsProviderInfo {
 }
 
 /**
- * Typed HTTP handlers exposed to `cadre-host-local-ui` for Fastify wiring.
+ * Typed HTTP handlers exposed to the local UI server for Fastify wiring.
  *
- * Like TrustCircleHandlers, these take typed objects and either return typed
- * results or throw a `NatError` whose `.code` the UI ticket maps to an HTTP
- * status code.
+ * These take typed objects and either return typed results or throw a
+ * `NatError` whose `.code` the error handler maps to an HTTP status code.
  */
 export interface NatHandlers {
   getStatus(): Promise<NatStatusSnapshot>;
@@ -155,5 +227,6 @@ export interface NatHandlers {
     config: Record<string, string>;
     externallyManaged?: boolean;
   }): Promise<NatStatusSnapshot>;
-  putSettings(body: Partial<Omit<NatSettingsFile, 'version'>>): Promise<NatStatusSnapshot>;
+  putSettings(body: Partial<Omit<NatSettingsFile, 'version' | 'forwards'>>): Promise<NatStatusSnapshot>;
+  putForward(nodeId: string, patch: ManualForwardPatch): Promise<NatStatusSnapshot>;
 }

package/src/{installer/__tests__/identity.test.ts → orchestrator/__tests__/identity-file.test.ts}

@@ -1,34 +1,34 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, rmSync, statSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { generateIdentity, loadIdentity } from '../identity.js';
-
-describe('installer identity', () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), 'cadre-host-id-'));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it('round-trips an Ed25519 keypair through the file', async () => {
-    const path = join(tmp, 'identity.key');
-    const generated = await generateIdentity(path);
-    expect(generated.peerId).toMatch(/^12D3Koo/);
-
-    const loaded = loadIdentity(path);
-    expect(loaded.peerId).toBe(generated.peerId);
-  });
-
-  it.runIf(process.platform !== 'win32')('persists with mode 0600 on POSIX', async () => {
-    const path = join(tmp, 'identity.key');
-    await generateIdentity(path);
-    const mode = statSync(path).mode & 0o777;
-    expect(mode).toBe(0o600);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { generateIdentity, loadIdentity } from '../identity-file.js';
+
+describe('identity file', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cadre-host-id-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('round-trips an Ed25519 keypair through the file', async () => {
+    const path = join(tmp, 'identity.key');
+    const generated = await generateIdentity(path);
+    expect(generated.peerId).toMatch(/^12D3Koo/);
+
+    const loaded = loadIdentity(path);
+    expect(loaded.peerId).toBe(generated.peerId);
+  });
+
+  it.runIf(process.platform !== 'win32')('persists with mode 0600 on POSIX', async () => {
+    const path = join(tmp, 'identity.key');
+    await generateIdentity(path);
+    const mode = statSync(path).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+});

package/src/orchestrator/__tests__/node-identity.test.ts

@@ -1,62 +1,62 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { ensureNodeIdentity, nodeIdentityPath } from '../node-identity.js';
-
-describe('ensureNodeIdentity', () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), 'cadre-node-id-'));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it('generates an identity inside the workdir on first call', async () => {
-    const { path, peerId } = await ensureNodeIdentity(tmp);
-    expect(path).toBe(nodeIdentityPath(tmp));
-    expect(path).toBe(join(tmp, 'identity.key'));
-    expect(peerId).toMatch(/^12D3Koo/);
-    expect(statSync(path).size).toBeGreaterThan(0);
-  });
-
-  // Reuse — not rotation — is the load-bearing property: a re-spawn of the same
-  // container must land on the same peer id or the cadre that admitted it sees a
-  // stranger.
-  it('reuses the existing key on a second call', async () => {
-    const first = await ensureNodeIdentity(tmp);
-    const bytesBefore = readFileSync(first.path);
-
-    const second = await ensureNodeIdentity(tmp);
-    expect(second.peerId).toBe(first.peerId);
-    expect(readFileSync(second.path).equals(bytesBefore)).toBe(true);
-  });
-
-  it('creates the workdir when it does not exist yet', async () => {
-    const workdir = join(tmp, 'nested', 'donated-1');
-    const { path, peerId } = await ensureNodeIdentity(workdir);
-    expect(path).toBe(join(workdir, 'identity.key'));
-    expect(peerId).toMatch(/^12D3Koo/);
-  });
-
-  // A key that is present but unreadable must FAIL the spawn, not fall through
-  // to `generateIdentity`. Regenerating would hand the cadre a stranger under
-  // the same containerId — silently reproducing the bug this module exists to
-  // fix — where a throw surfaces the damaged file to the operator.
-  it('throws rather than re-keying when the existing file does not decode', async () => {
-    const path = nodeIdentityPath(tmp);
-    writeFileSync(path, 'not a protobuf private key', 'utf8');
-
-    await expect(ensureNodeIdentity(tmp)).rejects.toThrow();
-    expect(readFileSync(path, 'utf8')).toBe('not a protobuf private key');
-  });
-
-  it.runIf(process.platform !== 'win32')('persists with mode 0600 on POSIX', async () => {
-    const { path } = await ensureNodeIdentity(tmp);
-    expect(statSync(path).mode & 0o777).toBe(0o600);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ensureNodeIdentity, nodeIdentityPath } from '../node-identity.js';
+
+describe('ensureNodeIdentity', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cadre-node-id-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('generates an identity inside the workdir on first call', async () => {
+    const { path, peerId } = await ensureNodeIdentity(tmp);
+    expect(path).toBe(nodeIdentityPath(tmp));
+    expect(path).toBe(join(tmp, 'identity.key'));
+    expect(peerId).toMatch(/^12D3Koo/);
+    expect(statSync(path).size).toBeGreaterThan(0);
+  });
+
+  // Reuse — not rotation — is the load-bearing property: a re-spawn of the same
+  // container must land on the same peer id or the cadre that admitted it sees a
+  // stranger.
+  it('reuses the existing key on a second call', async () => {
+    const first = await ensureNodeIdentity(tmp);
+    const bytesBefore = readFileSync(first.path);
+
+    const second = await ensureNodeIdentity(tmp);
+    expect(second.peerId).toBe(first.peerId);
+    expect(readFileSync(second.path).equals(bytesBefore)).toBe(true);
+  });
+
+  it('creates the workdir when it does not exist yet', async () => {
+    const workdir = join(tmp, 'nested', 'hn_1');
+    const { path, peerId } = await ensureNodeIdentity(workdir);
+    expect(path).toBe(join(workdir, 'identity.key'));
+    expect(peerId).toMatch(/^12D3Koo/);
+  });
+
+  // A key that is present but unreadable must FAIL the spawn, not fall through
+  // to `generateIdentity`. Regenerating would hand the cadre a stranger under
+  // the same containerId — silently reproducing the bug this module exists to
+  // fix — where a throw surfaces the damaged file to the operator.
+  it('throws rather than re-keying when the existing file does not decode', async () => {
+    const path = nodeIdentityPath(tmp);
+    writeFileSync(path, 'not a protobuf private key', 'utf8');
+
+    await expect(ensureNodeIdentity(tmp)).rejects.toThrow();
+    expect(readFileSync(path, 'utf8')).toBe('not a protobuf private key');
+  });
+
+  it.runIf(process.platform !== 'win32')('persists with mode 0600 on POSIX', async () => {
+    const { path } = await ensureNodeIdentity(tmp);
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+  });
+});