@serfab/cadre-host 1.13.0 → 1.14.0

package/dist/nat/types.d.ts

@@ -1,37 +1,80 @@
 /**
  * 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 {
-    portMode: PortForwardMode;
-    externalPort: number;
+/** The two ports of a hosted node that are mapped: libp2p TCP and libp2p WebSocket. */
+export type PortKind = 'tcp' | 'ws';
+/** Where a port's external route came from. */
+export type PortRouteSource = 'upnp' | 'manual';
+/** 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. */
+export type NodeVerdict = 'mapped' | 'manual' | '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."
+     */
+    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 {
+    upnpEnabled: boolean;
+    gateway: NatGatewayStatus;
     externalIp: string | null;
     externalIpDetectedAt: string | null;
     cgnatDetected: boolean;
+    /** Roll-up across running nodes; see `reachability.ts`. */
     directReachability: DirectReachability;
     lastTestedAt: string | null;
     ddns: NatDdnsStatus;
+    nodes: NodeReachability[];
 }
 /** DDNS sub-section of the status snapshot. */
 export interface NatDdnsStatus {
@@ -48,18 +91,26 @@ export interface NatDdnsStatus {
     /** Most recent error message, null when last attempt succeeded. */
     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. */
+    /** Whether to ask the router for port mappings at all. */
     upnpEnabled: boolean;
+    /** Per node id: the external port the user forwarded on their router, per port kind. */
+    forwards: Record<string, ManualForward>;
     ddns: NatDdnsSettings;
 }
 /** DDNS sub-section of `nat.json`. */
@@ -79,8 +130,8 @@ export interface NatDdnsSettings {
 }
 /** Typed error codes for NatError. */
 export type NatErrorCode = 'mapping_failed' | 'router_unreachable' | 'ip_detection_failed' | 'ddns_provider_unknown' | 'ddns_credentials_missing' | 'ddns_update_failed' | '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 declare class NatError extends Error {
     readonly code: NatErrorCode;
@@ -102,11 +153,10 @@ export interface DdnsProviderInfo {
     configFields: ReadonlyArray<DdnsConfigField>;
 }
 /**
- * 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>;
@@ -118,5 +168,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/dist/nat/types.js

@@ -1,14 +1,17 @@
 /**
  * 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).

package/dist/nat/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/nat/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkGH,6EAA6E;AAC7E,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGjC,YAAY,IAAkB,EAAE,OAAe;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/nat/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAiJH,6EAA6E;AAC7E,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGjC,YAAY,IAAkB,EAAE,OAAe;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/orchestrator/host-process-orchestrator.d.ts

@@ -1,5 +1,5 @@
-import { type Orchestrator, type OrchestratorCreateRequest, type OrchestratorCreateResult, type OrchestratorStats } from '@serfab/cadre-provider';
-import { type OwnerSpawnConfig, type HostProcessConfig, type ManagedNodeInfo, type NodePorts, type NodeStateListener } from './types.js';
+import { type Orchestrator, type OrchestratorCreateResult, type OrchestratorStats } from '@serfab/cadre-provider';
+import { type HostProcessConfig, type HostedSpawnRequest, type ManagedNodeInfo, type NodePorts, type NodeStateListener } from './types.js';
 /**
  * The libp2p listen addresses a managed child binds — its `CADRE_LISTEN_ADDRS`, one
  * entry per element: TCP on the `p2p` port and WebSocket on the `ws` port, both on
@@ -13,15 +13,6 @@ import { type OwnerSpawnConfig, type HostProcessConfig, type ManagedNodeInfo, ty
  * (`resolveTransportOptions` in `cadre-core/src/relay-addrs.ts`).
  */
 export declare function childListenAddrs(ports: Pick<NodePorts, 'p2p' | 'ws'>): string[];
-/** Fixed friendly id for the admin's owner node. */
-export declare const OWNER_CONTAINER_ID = "owner";
-/** Endpoint + bearer for the owner node's loopback admin channel (6.6). */
-export interface OwnerAdminEndpoint {
-    /** e.g. `http://127.0.0.1:<adminPort>`. */
-    baseUrl: string;
-    /** The child's `CADRE_STARTUP_TOKEN`, used as the admin bearer secret. */
-    token: string;
-}
 /**
  * Runs cadre nodes as plain Node child processes on the host.
  *
@@ -65,10 +56,10 @@ export declare class HostProcessOrchestrator implements Orchestrator {
     private readonly cliEntrypoint;
     /** Resolves push credentials fresh on every spawn (see HostProcessConfig). */
     private readonly pushResolver?;
+    /** The public addresses a node announces, asked at every spawn (see HostProcessConfig). */
+    private readonly announceAddrs?;
     /** State-change listeners — invoked when a handle's alive state changes. */
     private readonly stateListeners;
-    /** Persisted spawn config for the owner node (re-spawn on demand). */
-    private ownerConfig?;
     constructor(cfg: HostProcessConfig);
     /**
      * Read persisted state and re-attach to surviving children. Not part of
@@ -93,25 +84,27 @@ export declare class HostProcessOrchestrator implements Orchestrator {
     resolveDockerId(idOrDockerId: string): string | undefined;
     /**
      * Register a state-change listener. Invoked when a handle's `alive`
-     * transitions (child exit, manual stop). Returns an unsubscribe fn.
+     * transitions (create, child exit, manual stop) and once more, as `stopped`,
+     * when a handle is removed. Returns an unsubscribe fn.
      */
     onStateChange(listener: NodeStateListener): () => void;
     /**
-     * Spawn a generic managed node — the donated-node path (the requester's cadre,
-     * pinned to the *requester's* owner key). The node is given its own protobuf
-     * identity key inside its workdir (`ensureNodeIdentity`, reused across
+     * Spawn a managed node — a hosted node for some cadre, started waiting to be
+     * claimed when the request carries a `claimSecret`, or redeeming the cadre
+     * invitation it carries as `invitation`. The node is given its own
+     * protobuf identity key inside its workdir (`ensureNodeIdentity`, reused across
      * re-spawns of the same containerId), which is what makes its peer id stable
      * across restarts AND what makes its node-local stores durable: `cadre-cli
      * start` opens the file-backed bootstrap-peer, trusted-owner and strand
      * network-state stores in the node's state directory, which defaults to the
      * directory holding the `cadre.json` written here — the same workdir.
-     * Terminating the loan (`removeContainer`) deletes the workdir, so the key and
+     * Removing the node (`removeContainer`) deletes the workdir, so the key and
      * every store go with it.
      */
-    createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult>;
+    createContainer(request: HostedSpawnRequest): Promise<OrchestratorCreateResult>;
     /**
      * Remove the working directory a spawn created for `containerId` when no
-     * handle owns it — the cleanup of last resort for a donation record that
+     * handle owns it — the cleanup of last resort for a hosted-node record that
      * never got a `dockerId` (the host died between `ensureNodeIdentity` and the
      * handle write, so `createContainer`'s own unwind never ran). Returns whether
      * anything was removed.
@@ -144,33 +137,17 @@ export declare class HostProcessOrchestrator implements Orchestrator {
      */
     private resolvePush;
     /**
-     * Ensure the admin's owner node is running, spawning it if absent or
-     * dead. Idempotent: a second call with the node already alive returns the
-     * existing handle without launching a second child. The spawn parameters
-     * are persisted so a later `/api/nodes/:id/{start,restart}` (or an
-     * orchestrator restart) can re-spawn it without re-supplying them.
-     *
-     * The owner node is spawned as `cadre-cli start --owner
-     * --admin-port <p> --identity-file <identityPath>` so it carries the
-     * host's libp2p identity, founds/joins the control network, and exposes the
-     * loopback admin channel the manager delegates to.
+     * The public addresses the node about to spawn announces. A hook that throws costs
+     * the node its public addresses, never its start: it still binds and is reachable
+     * on its LAN addresses, and `NatService` restarts it once the addresses it should
+     * announce differ from these.
      */
-    ensureOwnerNode(cfg?: OwnerSpawnConfig): Promise<ManagedNodeInfo>;
-    /** Endpoint + bearer for the owner node's admin channel, if spawned. */
-    getOwnerAdminEndpoint(): OwnerAdminEndpoint | undefined;
-    /** Whether spawn parameters for the owner node are known (persisted). */
-    hasOwnerConfig(): boolean;
-    /** Whether the given friendly/docker id refers to the owner node. */
-    isOwnerNode(idOrDockerId: string): boolean;
-    /** Stop the owner node (if running). Used on graceful shutdown. */
-    stopOwnerNode(): Promise<void>;
-    /** Stop the owner node (if running), then re-spawn it from saved config. */
-    restartOwnerNode(): Promise<ManagedNodeInfo>;
+    private announceAddrsFor;
     /**
-     * Core spawn mechanics shared by `createContainer` and `ensureOwnerNode`.
+     * Core spawn mechanics behind `createContainer`.
      *
      * The caller has already allocated `ports` and **owns their lifetime**: this
-     * method never releases them, so every caller must release on any throw out
+     * method never releases them, so the caller must release on any throw out
      * of here (it has to unwind its handle drop on the same path anyway — see
      * `restoreDroppedHandles`).
      *
@@ -184,7 +161,7 @@ export declare class HostProcessOrchestrator implements Orchestrator {
     private launchChild;
     /**
      * Refuse to re-spawn `containerId` while a previous child of it may still be
-     * running. Both spawn paths call this as their last `await` before the handle
+     * running. `createContainer` calls this as its last `await` before the handle
      * drop, so a refusal happens while nothing has been released, no token rotated
      * and no child launched — the caller sees an ordinary failed spawn.
      *
@@ -202,9 +179,6 @@ export declare class HostProcessOrchestrator implements Orchestrator {
      *   is already bound, refuse. The pid is never killed on that evidence — it may
      *   not be ours.
      *
-     * `overrides` are the ports the caller will override on top of the reused ones
-     * (the owner node's configured p2p port); `owner` adds the admin channel.
-     *
      * NOTE: the probe cannot see a re-attached child still loading its modules —
      * `cadre-cli start` writes its token and only then binds, so a child in that
      * window shows neither, and a re-spawn launched then races it for the ports.
@@ -225,9 +199,9 @@ export declare class HostProcessOrchestrator implements Orchestrator {
     /**
      * Drop any handle left over from a previous spawn of the same `containerId`
      * and release its ports. Handles are keyed by the per-spawn `dockerId`, so
-     * without this a re-spawn (donated-node respawn) would strand the prior
+     * without this a re-spawn (a hosted node's respawn) would strand the prior
      * handle in the map forever, leaking its ports from a bounded range each
-     * time. Mirrors the same cleanup in `ensureOwnerNode`.
+     * time.
      *
      * DO NOT delete the workdir: the identity key and node-local stores
      * (trusted-owner anchor, retained cold-start dial targets) live there and are
@@ -237,16 +211,16 @@ export declare class HostProcessOrchestrator implements Orchestrator {
      * Releasing the ports hands them straight back to the allocator, and the
      * re-spawn then takes those same ports as overrides (`reusedNodePorts`), so a
      * re-spawn while the *previous* child is still listening would bind-clash.
-     * Callers must therefore never drop a live child, and both do so only after
+     * The caller must therefore never drop a live child, and does so only after
      * {@link refuseRespawnOverLiveChild} has passed. A caller that needs to replace
      * a live child must stop it first.
      *
      * **The drop is reversible.** It happens before the launch can fail, so the
-     * dropped handles are returned and every caller restores them via
+     * dropped handles are returned and the caller restores them via
      * {@link restoreDroppedHandles} when the launch throws — otherwise the caller
      * would be left holding a dockerId this orchestrator no longer knows, and the
      * node's workdir could never be reclaimed. On a *successful* spawn the drop
-     * stands: `DonationService.abandonRespawn` depends on the old handle being
+     * stands: `HostedNodeService.abandonRespawn` depends on the old handle being
      * gone by then.
      */
     private dropStaleHandle;
@@ -257,10 +231,10 @@ export declare class HostProcessOrchestrator implements Orchestrator {
      *
      * **Precondition: the drop → launch window is synchronous.** Restoring is
      * sound only because nothing can have taken those ports or run cleanup
-     * against the handle in between — `launchChild` contains no `await` and both
-     * callers resolve push credentials *before* their drop. `launchChild`'s half
+     * against the handle in between — `launchChild` contains no `await` and the
+     * caller resolves push credentials *before* its drop. `launchChild`'s half
      * is enforced: its declared return type is not a Promise, so adding an
-     * `await` there is a compile error. The callers' half is not — an `await`
+     * `await` there is a compile error. The caller's half is not — an `await`
      * slipped between a drop and its launch silently breaks this.
      *
      * No `persist()` here: `state.json` is rewritten only by `launchChild` and
@@ -278,8 +252,6 @@ export declare class HostProcessOrchestrator implements Orchestrator {
     private restoreDroppedHandles;
     /** A managed node's own directory under `rootDir` — config, log, storage, identity. */
     private workdirFor;
-    /** Locate the owner node's handle, if one has been spawned. */
-    private findOwnerHandle;
     /**
      * Inverse of {@link releasePorts} — hold a handle's whole port set against
      * the allocator. Used both to rehydrate on `init` and to undo a drop whose
@@ -299,20 +271,6 @@ export declare class HostProcessOrchestrator implements Orchestrator {
     getLogs(dockerId: string, tail?: number): Promise<string>;
     private requireHandle;
     private buildChildConfig;
-    /**
-     * Child config for the **host's own personal cadre** owner node — the opt-in
-     * "founder" persona spawned only when `ownCadre.enabled` (see
-     * docs/cadre-host.md § Two roles: donor and founder). It founds/joins the
-     * control network for the host's own `partyId` (no bootstrap peers — it is the
-     * founding node of the host's *own* cadre) and carries the host identity via
-     * `--identity-file` (passed as a spawn arg).
-     *
-     * This is NOT the node cadre-host donates to a requester. Donated nodes are
-     * generic (`createContainer` / `buildChildConfig`): they join the
-     * **requester's** cadre via bootstrap peers and pin the *requester's* owner
-     * key — they never run a host genesis.
-     */
-    private buildOwnerChildConfig;
     private persist;
     private emitStateChange;
     private toPersisted;