@serfab/cadre-host 1.14.0 → 1.15.0

package/src/hosted/claim-details.ts

@@ -3,11 +3,10 @@
  * `HostedNodeService.claimDetails` reads the child's `/status` and hands it here.
  */
 
-import { multiaddr, CODE_IP4, CODE_IP6, CODE_P2P_CIRCUIT } from '@multiformats/multiaddr';
+import { encodeNodeClaimPayload, selectNodeClaimAddresses, withClaimDestination } from '@serfab/cadre-core';
 
-import { encodeNodeClaimPayload } from '@serfab/cadre-core';
-
-import type { NodeReachability } from '../nat/types.js';
+import type { ClaimAddressSettings } from '../installer/config.js';
+import type { NetworkMode, NodeReachability } from '../nat/types.js';
 import type { NodeStatus } from './node-status.js';
 import { HostedNodeError } from './types.js';
 
@@ -16,17 +15,21 @@ export interface ClaimDetails {
   /** `encodeNodeClaimPayload` of the three fields below — the text the QR code carries. */
   payload: string;
   peerId: string;
-  /** Public addresses first (TCP, then WebSocket), then the node's own non-loopback LAN addresses. */
+  /** Public names (or public IPs when there is no name), then the one LAN address; see {@link dialAddressesFor}. */
   multiaddrs: string[];
   /** The NAT layer's verdict for the node, or null when it has no entry yet. A phone at home reaches the LAN address either way. */
   reachability: NodeReachability | null;
 }
 
-/** The NAT layer's two answers the claim details need. `NatService` satisfies this. */
+/** The NAT layer's answers the claim details need. `NatService` satisfies this. */
 export interface HostedNodeAddressSource {
   /** The node's public multiaddrs (no `/p2p/` suffix), TCP then WebSocket. */
   publicAddressesFor(nodeId: string, ports: { p2p: number; ws?: number }): string[];
-  getStatus(): { nodes: NodeReachability[] };
+  /**
+   * `gateway.lanAddress` is this machine's address on the router's subnet, when a UPnP gateway
+   * answered; `network.mode` is whether it sits behind a router (`lan`) or holds a public IPv4.
+   */
+  getStatus(): { nodes: NodeReachability[]; gateway: { lanAddress: string | null }; network: { mode: NetworkMode } };
 }
 
 /** One node's claim details, from its record's secret, its `/status`, and its ports. */
@@ -37,6 +40,10 @@ export interface ClaimDetailsInput {
   /** The orchestrator handle's ports; absent, the code carries LAN addresses only. */
   ports: { p2p: number; ws?: number } | undefined;
   addresses: HostedNodeAddressSource;
+  /** `host.config.json`'s `claimAddresses.addrs`: exact addresses replacing the automatic choice. */
+  exactAddrs?: readonly string[];
+  /** The LAN address to keep, as {@link claimLanAddress} resolved it. */
+  lan: string | null | undefined;
 }
 
 /**
@@ -58,39 +65,39 @@ export function buildClaimDetails(input: ClaimDetailsInput): ClaimDetails {
 }
 
 /**
- * The addresses the QR code names, in dial order: the node's public addresses
- * from the NAT layer with the peer id appended (a phone away from home needs
- * these), then the node's own non-loopback addresses as `/status` reports them
- * (they already carry `/p2p/`; a phone at home dials these). Loopback and relay
- * entries are dropped — nothing off this machine can use the former, and no
- * hosted node holds a relay reservation today.
+ * The LAN address a node code keeps (`selectNodeClaimAddresses`' `lan`), from `claimAddresses.lan`:
+ * `'none'` is null; an IP is itself; `'auto'` (default) is null in public-IP mode (no phone shares
+ * a LAN with a VPS), else the gateway's `lanAddress`, else the machine's primary address
+ * (`primaryLan`, probed only then), else undefined (keep every private address).
  */
-function dialAddressesFor({ id, status, ports, addresses }: ClaimDetailsInput): string[] {
-  const publicAddrs = ports
-    ? addresses.publicAddressesFor(id, ports).map((a) => `${a}/p2p/${status.peerId}`)
-    : [];
-  const lanAddrs = status.multiaddrs.filter((a) => isDialableFromLan(a));
-  return [...new Set([...publicAddrs, ...lanAddrs])];
+export async function claimLanAddress(
+  settings: ClaimAddressSettings | undefined,
+  addresses: HostedNodeAddressSource,
+  primaryLan: () => Promise<string | undefined>,
+): Promise<string | null | undefined> {
+  const lan = settings?.lan ?? 'auto';
+  if (lan === 'none') return null;
+  if (lan !== 'auto') return lan;
+  const { network, gateway } = addresses.getStatus();
+  if (network.mode === 'public') return null;
+  return gateway.lanAddress ?? await primaryLan();
 }
 
 /**
- * Whether an address the node reports is one a phone on the host's LAN can dial:
- * not loopback, not the unspecified address (libp2p expands a `0.0.0.0` listen into
- * interface addresses, but a raw one names nothing to dial), not a relay circuit,
- * and parsable. A DNS address passes (it names something off this machine); an
- * address with no host component at all is dropped.
+ * The addresses the QR code names, in dial order. A phone dials each in turn on its own
+ * timeout, so every address it cannot reach delays a failing claim and enlarges the code.
+ *
+ * - With `exactAddrs`, exactly those, each given the node's peer id.
+ * - Otherwise cadre-core's `selectNodeClaimAddresses` over the NAT layer's public addresses
+ *   and the node's own (`/status`): WebSocket and relay only (a phone has no TCP), public
+ *   names before raw public IPs, and of the private addresses only `lan`. Docker bridges,
+ *   VPNs and other interfaces a phone cannot reach are left out.
  */
-function isDialableFromLan(addr: string): boolean {
-  let components: ReturnType<ReturnType<typeof multiaddr>['getComponents']>;
-  try {
-    components = multiaddr(addr).getComponents();
-  } catch {
-    return false;
-  }
-  if (components.some((c) => c.code === CODE_P2P_CIRCUIT)) return false;
-  const host = components[0];
-  if (!host?.value) return false;
-  if (host.code === CODE_IP4) return !host.value.startsWith('127.') && host.value !== '0.0.0.0';
-  if (host.code === CODE_IP6) return host.value !== '::1' && host.value !== '::';
-  return true;
+function dialAddressesFor({ id, status, ports, addresses, exactAddrs, lan }: ClaimDetailsInput): string[] {
+  // NOTE: `claimAddresses.addrs` is host-wide, so every hosted node's code carries the same
+  // addresses with its own peer id; that reaches each node only if they route per node (one
+  // node, or a port per node). If several nodes behind one proxy is reported, make it per node.
+  if (exactAddrs && exactAddrs.length > 0) return [...new Set(exactAddrs.map((a) => withClaimDestination(a, status.peerId)))];
+  const publicAddrs = ports ? addresses.publicAddressesFor(id, ports) : [];
+  return selectNodeClaimAddresses([...publicAddrs, ...status.multiaddrs], status.peerId, { lan });
 }

package/src/hosted/hosted-node-service.ts

@@ -2,10 +2,12 @@ import { randomBytes } from 'node:crypto';
 import debug from 'debug';
 
 import { CLAIM_SECRET_BYTES, decodeCadreInvitation, type CadreInvitation } from '@serfab/cadre-core';
+import { primaryLanAddress } from '@serfab/cadre-core/primary-lan-address';
 import type { Orchestrator, OrchestratorCreateResult } from '@serfab/cadre-provider';
 
 import type { HostedSpawnRequest, ManagedNodeInfo, NodeStateListener } from '../orchestrator/types.js';
-import { buildClaimDetails, type ClaimDetails, type HostedNodeAddressSource } from './claim-details.js';
+import type { ClaimAddressSettings } from '../installer/config.js';
+import { buildClaimDetails, claimLanAddress, type ClaimDetails, type HostedNodeAddressSource } from './claim-details.js';
 import type { HostedNodeStore } from './hosted-node-store.js';
 import { HostedNodeWatcher } from './hosted-node-watcher.js';
 import { PLACEHOLDER_PARTY, errorMessage, readNodeStatus, statusUrlFor } from './node-status.js';
@@ -130,6 +132,10 @@ export interface HostedNodeServiceOptions {
   store: HostedNodeStore;
   /** The NAT layer, for the node's public addresses and reachability verdict. */
   addresses: HostedNodeAddressSource;
+  /** `host.config.json`'s `claimAddresses`, read on every claim-code request so an edit applies at once. */
+  claimAddressSettings?: () => ClaimAddressSettings | undefined;
+  /** The machine's primary address, the `lan: 'auto'` fallback when no UPnP gateway answered. */
+  primaryLan?: () => Promise<string | undefined>;
   /** Clock override for tests. */
   now?: () => Date;
 }
@@ -159,6 +165,8 @@ export class HostedNodeService {
   private readonly orchestrator: HostedNodeOrchestrator;
   private readonly store: HostedNodeStore;
   private readonly addresses: HostedNodeAddressSource;
+  private readonly claimAddressSettings: () => ClaimAddressSettings | undefined;
+  private readonly primaryLan: () => Promise<string | undefined>;
   private readonly now: () => Date;
   private readonly listeners = new Set<HostedNodeChangeListener>();
   private readonly watcher: HostedNodeWatcher;
@@ -171,6 +179,8 @@ export class HostedNodeService {
     this.orchestrator = opts.orchestrator;
     this.store = opts.store;
     this.addresses = opts.addresses;
+    this.claimAddressSettings = opts.claimAddressSettings ?? (() => undefined);
+    this.primaryLan = opts.primaryLan ?? primaryLanAddress;
     this.now = opts.now ?? (() => new Date());
     this.watcher = new HostedNodeWatcher({
       store: this.store,
@@ -335,7 +345,17 @@ export class HostedNodeService {
     const { secret } = node.join;
     const status = await readNodeStatus(node.statusEndpoint);
     this.recordPeerId(id, status.peerId);
-    return buildClaimDetails({ id, secret, status, ports: this.orchestrator.getNode?.(id)?.ports, addresses: this.addresses });
+    const settings = this.claimAddressSettings();
+    const exactAddrs = settings?.addrs ?? [];
+    return buildClaimDetails({
+      id,
+      secret,
+      status,
+      ports: this.orchestrator.getNode?.(id)?.ports,
+      addresses: this.addresses,
+      exactAddrs,
+      lan: exactAddrs.length > 0 ? undefined : await claimLanAddress(settings, this.addresses, this.primaryLan),
+    });
   }
 
   /** Cache the peer id on the record, once. Best-effort: the claim details do not depend on it. */
@@ -767,14 +787,13 @@ function spawnRequestFor(node: HostedNode): HostedSpawnRequest {
   const base: HostedSpawnRequest = {
     containerId: node.id,
     partyId: node.partyId,
-    bootstrapNodes: [],
     profile: node.profile,
   };
   if (node.join.kind === 'claim') return { ...base, claimSecret: node.join.secret };
   return node.status === 'joined' ? base : { ...base, invitation: node.join.encoded };
 }
 
-/** The record fields a spawn result lands. `seedToken` and `seedEndpoint` are the provider's shape; cadre-host ignores both. */
+/** The record fields a spawn result lands. */
 function handlesOf(result: OrchestratorCreateResult): SpawnedHandles {
   return { dockerId: result.dockerId, statusEndpoint: statusUrlFor(result.healthEndpoint) };
 }