@serfab/cadre-host 1.13.0 → 1.15.0

package/src/index.ts

@@ -4,18 +4,12 @@
  * This package is the sibling of @serfab/cadre-provider for self-hosted
  * basement-PC deployments. It depends on @serfab/cadre-provider for the
  * orchestration interface and container lifecycle types but ships its own
- * orchestrator (host processes, not Docker), auth (trust circle, not API
- * keys), installer, NAT layer, and local management UI.
+ * orchestrator (host processes, not Docker), the hosted-node service behind
+ * "Join a cadre", installer, NAT layer, and local management UI.
  *
- * Implementations of HostProcessOrchestrator, TrustCircleAuth, the NAT
- * layer, installer scripts, and the local UI live in sibling subdirectories
- * under src/ and are added by their respective tickets:
- *
- *   - cadre-host-process-orchestrator     [DONE]
- *   - cadre-host-trust-circle             [DONE]
- *   - cadre-host-nat
- *   - cadre-host-installer
- *   - cadre-host-local-ui
+ * HostProcessOrchestrator, the hosted-node layer, the NAT layer, the
+ * installer, and the local UI server each live in a sibling subdirectory
+ * under src/.
  */
 
 export type {
@@ -27,84 +21,57 @@ export type {
   ContainerResources,
 } from '@serfab/cadre-provider';
 
-export { HostProcessOrchestrator, OWNER_CONTAINER_ID } from './orchestrator/index.js';
+export { HostProcessOrchestrator } from './orchestrator/index.js';
 export type {
   HostProcessConfig,
+  HostedSpawnRequest,
   PersistedHandle,
   ManagedNodeInfo,
   NodeStateListener,
   NodePorts,
-  OwnerAdminEndpoint,
-  OwnerSpawnConfig,
 } from './orchestrator/index.js';
 
-export { OwnerNodeClient, OwnerNodeUnavailableError } from './owner/index.js';
-export type { OwnerNodeClientOptions } from './owner/index.js';
-
-export {
-  TrustCircleService,
-  TrustCircleStore,
-  TrustCircleError,
-  createTrustCircleHandlers,
-  parseDuration,
-  ensureSelfLabel,
-  DEFAULT_INVITE_TTL_MS,
-} from './auth/index.js';
-export type {
-  TrustCircleServiceOptions,
-  CadreNodeLike,
-  TrustCircleMember,
-  PendingInvite,
-  TrustCircleFile,
-  TrustCircleSnapshot,
-  TrustCircleHandlers,
-  TrustCircleErrorCode,
-} from './auth/index.js';
-
-/* ──────────────── strand management ──────────────── */
-
-export { StrandService, StrandError, createStrandHandlers } from './strands/index.js';
-export type {
-  StrandServiceOptions,
-  CadreNodeLike as StrandCadreNodeLike,
-  StrandSummary,
-  StrandListSnapshot,
-  StrandRemovalResult,
-  StrandHandlers,
-  StrandErrorCode,
-} from './strands/index.js';
-
-/* ──────────────── donation grant tokens ──────────────── */
+/* ──────────────── hosted nodes ("Join a cadre") ──────────────── */
 
 export {
-  GrantStore,
-  GrantService,
-  createGrantAdminHandlers,
-  GrantError,
-  DEFAULT_MAX_NODES,
-  DonationStore,
-  DonationService,
-  DonationError,
-} from './donation/index.js';
+  HostedNodeStore,
+  HostedNodeService,
+  HostedNodeSupervisor,
+  HostedNodeError,
+  HOSTED_NODE_SPAWNING_TTL_MS,
+  HOSTED_NODE_REAP_SWEEP_MS,
+  HOSTED_NODE_CLAIM_POLL_MS,
+  HOSTED_NODE_CONNECTED_POLL_MS,
+  HOSTED_NODE_RESPAWN_BACKOFF_BASE_MS,
+  HOSTED_NODE_RESPAWN_BACKOFF_MAX_MS,
+  HOSTED_NODE_RESPAWN_MAX_ATTEMPTS,
+  HOSTED_NODE_RESPAWN_HEALTHY_MS,
+  HOSTED_NODE_RESPAWN_SWEEP_MS,
+  PLACEHOLDER_PARTY,
+} from './hosted/index.js';
 export type {
-  Grant,
-  GrantDenyReason,
-  GrantValidation,
-  GrantValidator,
-  GrantFile,
-  GrantAdminHandlers,
-  GrantErrorCode,
-  GrantServiceOptions,
-  Donation,
-  DonationView,
-  DonationStatus,
-  DonationFile,
-  DonationErrorCode,
-  DonationProvisionRequest,
-  DonationSeedResult,
-  DonationPeerInfo,
-  DonationServiceOptions,
-} from './donation/index.js';
+  ClaimDetails,
+  HostedNode,
+  HostedNodeAddressSource,
+  HostedNodeChange,
+  HostedNodeChangeKind,
+  HostedNodeChangeListener,
+  HostedNodeErrorCode,
+  HostedNodeClaimJoin,
+  HostedNodeFile,
+  HostedNodeInvitationJoin,
+  HostedNodeJoin,
+  HostedNodeJoinView,
+  HostedNodeOrchestrator,
+  HostedNodeServiceOptions,
+  HostedNodeStatus,
+  HostedNodeSupervisorOptions,
+  HostedNodeView,
+  JoinOptions,
+  RespawnOptions,
+  RespawnResult,
+  SupervisedOrchestrator,
+} from './hosted/index.js';
 
 export { Installer, readHostConfig, updateHostConfig, writeHostConfig } from './installer/index.js';
 export type {
@@ -179,11 +146,16 @@ export {
   NatStore,
   NatError,
   createNatHandlers,
+  NAT_UNMAP_GRACE_MS,
+  NAT_RECONCILE_INTERVAL_MS,
+  NAT_IP_REDETECT_INTERVAL_MS,
   ExternalIpDetector,
-  PortMapperService,
-  createDefaultPortMapper,
-  evaluateReachability,
-  buildInviteAddresses,
+  UpnpPortMapper,
+  pickLanAddress,
+  evaluateNodeReachability,
+  evaluateHostReachability,
+  buildPublicAddresses,
+  isPublicIpv4,
   BUILTIN_PROVIDERS,
   getProvider,
   listProviders,
@@ -196,30 +168,41 @@ export {
   KEYTAR_SERVICE,
   DEFAULT_LEASE_TTL_MS,
   DEFAULT_REFRESH_MS,
+  GATEWAY_DISCOVERY_TIMEOUT_MS,
   isPlausibleIp,
 } from './nat/index.js';
 export type {
   NatServiceOptions,
-  CadreNodeLike as NatCadreNodeLike,
+  NatNodeSource,
+  NatChangeListener,
+  NodeAddressesStaleListener,
   NatStatusSnapshot,
+  NatGatewayStatus,
   NatDdnsStatus,
   NatSettingsFile,
   NatDdnsSettings,
   NatHandlers,
   NatErrorCode,
-  PortForwardMode,
   DirectReachability,
+  NodeReachability,
+  NodeVerdict,
+  PortKind,
+  PortRoute,
+  PortRouteSource,
+  ManualForward,
+  ManualForwardPatch,
   DdnsProviderInfo,
   DdnsConfigField,
   ExternalIpResult,
   RouterIpProbe,
   ExternalIpDetectorOptions,
   PortMapper,
-  PortMappingResult,
-  PortMapOptions,
-  PortMapperState,
-  PortMapperServiceOptions,
-  BuildInviteAddressesInput,
+  GatewayInfo,
+  PortMapRequest,
+  PortMapResult,
+  NodeVerdictInput,
+  NodeVerdictResult,
+  PublicAddressInput,
   DdnsProvider,
   DdnsProviderDeps,
   DdnsUpdaterOptions,
@@ -236,8 +219,6 @@ export {
   HostSettingsStore,
 } from './server/index.js';
 export type {
-  FounderServices,
-  HostRole,
   LocalUiServer,
   LocalUiServerOptions,
   LocalUiEvent,

package/src/installer/__tests__/config.test.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { readHostConfig, updateHostConfig, writeHostConfig, hostOwnsCadre, type HostConfigFile } from '../config.js';
+import { readHostConfig, updateHostConfig, writeHostConfig, type HostConfigFile } from '../config.js';
 
 describe('host.config.json round-trip', () => {
   let tmp: string;
@@ -18,12 +18,10 @@ describe('host.config.json round-trip', () => {
 
   function makeCfg(overrides: Partial<HostConfigFile> = {}): HostConfigFile {
     return {
-      version: 2,
+      version: 3,
       installId: 'abc123',
       uiPort: 8765,
-      libp2pPort: 4001,
       dataDir: tmp,
-      identityPath: join(tmp, 'identity.key'),
       upnpEnabled: true,
       installedAt: '2026-01-01T00:00:00.000Z',
       installerVersion: '0.6.0',
@@ -39,10 +37,11 @@ describe('host.config.json round-trip', () => {
     expect(readHostConfig(path)).toEqual(cfg);
   });
 
-  it('rejects v1 files without rewriting them', () => {
+  // A version-2 file is a founder-era install: it is refused, never migrated.
+  it('rejects v2 files without rewriting them', () => {
     const path = join(tmp, 'host.config.json');
-    const v1 = {
-      version: 1,
+    const v2 = {
+      version: 2,
       installId: 'abc123',
       uiPort: 8765,
       libp2pPort: 4001,
@@ -51,10 +50,12 @@ describe('host.config.json round-trip', () => {
       upnpEnabled: true,
       installedAt: '2026-01-01T00:00:00.000Z',
       installerVersion: '0.6.0',
+      updates: { autoApply: false },
+      ownCadre: { enabled: true },
     };
-    const raw = JSON.stringify(v1);
+    const raw = JSON.stringify(v2);
     writeFileSync(path, raw);
-    expect(() => readHostConfig(path)).toThrow(/unsupported version=1/);
+    expect(() => readHostConfig(path)).toThrow(/unsupported version=2/);
     expect(readFileSync(path, 'utf8')).toBe(raw);
   });
 
@@ -79,20 +80,20 @@ describe('host.config.json round-trip', () => {
 
   it('rejects missing required fields', () => {
     const path = join(tmp, 'host.config.json');
-    writeFileSync(path, JSON.stringify({ version: 2, uiPort: 1234 }));
+    writeFileSync(path, JSON.stringify({ version: 3, uiPort: 1234 }));
     expect(() => readHostConfig(path)).toThrow(/missing required fields/);
   });
 
   it('refuses to write the wrong version', () => {
     const path = join(tmp, 'host.config.json');
-    expect(() => writeHostConfig(path, { ...makeCfg(), version: 3 as never })).toThrow(/version=3/);
+    expect(() => writeHostConfig(path, { ...makeCfg(), version: 2 as never })).toThrow(/version=2/);
   });
 
   it('update patches fields and re-stamps the current version', () => {
     const path = join(tmp, 'host.config.json');
     writeHostConfig(path, makeCfg());
     const next = updateHostConfig(path, { updates: { autoApply: true } });
-    expect(next.version).toBe(2);
+    expect(next.version).toBe(3);
     expect(next.updates).toEqual({ autoApply: true });
     expect(next.installId).toBe('abc123');
     expect(readHostConfig(path)).toEqual(next);
@@ -102,33 +103,7 @@ describe('host.config.json round-trip', () => {
     const path = join(tmp, 'host.config.json');
     writeHostConfig(path, makeCfg());
     const patch = { version: 1 } as unknown as Partial<Omit<HostConfigFile, 'version'>>;
-    expect(updateHostConfig(path, patch).version).toBe(2);
-    expect(readHostConfig(path).version).toBe(2);
-  });
-
-  it('round-trips ownCadre and hostOwnsCadre reflects it', () => {
-    const path = join(tmp, 'host.config.json');
-    const cfg = makeCfg({ ownCadre: { enabled: true } });
-    writeHostConfig(path, cfg);
-    const read = readHostConfig(path);
-    expect(read.ownCadre).toEqual({ enabled: true });
-    expect(hostOwnsCadre(read)).toBe(true);
-  });
-
-  it('treats an absent ownCadre as donor-only (hostOwnsCadre false)', () => {
-    // A pre-ownCadre v2 config (field absent) must read back cleanly and be
-    // donor-only — no migration, field stays absent.
-    const path = join(tmp, 'host.config.json');
-    const cfg = makeCfg();
-    writeHostConfig(path, cfg);
-    const read = readHostConfig(path);
-    expect(read.ownCadre).toBeUndefined();
-    expect(hostOwnsCadre(read)).toBe(false);
-  });
-
-  it('rejects a malformed ownCadre shape', () => {
-    const path = join(tmp, 'host.config.json');
-    writeFileSync(path, JSON.stringify({ ...makeCfg(), ownCadre: { enabled: 'yes' } }));
-    expect(() => readHostConfig(path)).toThrow(/missing required fields/);
+    expect(updateHostConfig(path, patch).version).toBe(3);
+    expect(readHostConfig(path).version).toBe(3);
   });
 });