@serfab/cadre-host 1.13.0 → 1.14.0

package/src/server/index.ts

@@ -1,267 +1,223 @@
-/**
- * Public surface for the cadre-host local UI server.
- *
- * `createLocalUiServer(opts)` wires:
- *   - the origin guard + error handler
- *   - existing trust-circle / NAT / update typed handlers, mounted at
- *     `/auth/*`, `/nat/*`, `/update/*` (the CLI contract)
- *   - new UI-only routes under `/api/*` (status, nodes, settings, events)
- *   - the static SPA mount at `/`
- *
- * Callers (cadre-host start) own the subsystems and pass them in. The
- * server doesn't construct them — start has to own their lifecycle anyway
- * (orchestrator init, trust-circle/NAT bring-up, update timer).
- */
-
-import type { FastifyInstance } from 'fastify';
-
-import type { HostProcessOrchestrator } from '../orchestrator/index.js';
-import type { TrustCircleService } from '../auth/index.js';
-import { createTrustCircleHandlers } from '../auth/index.js';
-import type { NatService } from '../nat/index.js';
-import { createNatHandlers } from '../nat/index.js';
-import type { StrandService } from '../strands/index.js';
-import { createStrandHandlers } from '../strands/index.js';
-import type { UpdateService } from '../update/index.js';
-import { createUpdateHandlers } from '../update/index.js';
-import type { GrantService, DonationService } from '../donation/index.js';
-import { createGrantAdminHandlers } from '../donation/index.js';
-
-import { EventBus } from './events/bus.js';
-import { registerSseRoute } from './events/sse-route.js';
-import { registerErrorHandler } from './error-handler.js';
-import { registerOriginGuard } from './origin-guard.js';
-import { registerStaticMount } from './static.js';
-import { buildFastify, startListening, stopListening } from './server.js';
-import { registerNatRoutes } from './routes/nat.js';
-import { registerTrustCircleRoutes } from './routes/trust-circle.js';
-import { registerStrandRoutes } from './routes/strands.js';
-import { registerUpdateRoutes } from './routes/update.js';
-import { registerStatusRoute, type HostRole } from './routes/status.js';
-import { registerNodesRoutes } from './routes/nodes.js';
-import { registerSettingsRoutes } from './routes/settings.js';
-import { registerGrantsAdminRoutes } from './routes/grants-admin.js';
-import { registerGrantsRoutes } from './routes/grants.js';
-import { HostSettingsStore } from './settings-store.js';
-
-/**
- * The host's own-cadre services. All three or none: they share the owner node,
- * and grouping them makes the role `/api/status` reports impossible to disagree
- * with the surfaces actually mounted.
- */
-export interface FounderServices {
-  trustCircle: TrustCircleService;
-  nat: NatService;
-  strands: StrandService;
-}
-
-export interface LocalUiServerOptions {
-  /** Configured UI port from host.config.json. May be re-bound on collision. */
-  uiPort: number;
-  /** Resolved data dir (passed by cadre-host start). */
-  dataDir: string;
-  /** Wired dependencies — all owned by the caller. */
-  orchestrator: HostProcessOrchestrator;
-  /**
-   * The host's own-cadre services — present iff `ownCadre.enabled` (the
-   * founder role). Absent in donor-only mode, where `/auth/*`, `/nat/*` and
-   * `/api/strands` stay unmounted and 404 through the static handler, and
-   * `/api/status` reports `role: 'donor'`.
-   */
-  founder?: FounderServices;
-  /** Optional — 6.4.2 lands this; nullable while still iterating. */
-  update?: UpdateService;
-  /**
-   * Donation grant layer. When present, mounts the loopback admin surface at
-   * `/grants-admin` (issue/list/revoke, plus donated-node teardown when
-   * `donations` is wired too). Optional so existing callers/tests that don't
-   * exercise donations need not wire it.
-   */
-  grants?: GrantService;
-  /**
-   * Donation lifecycle service. When present (alongside `grants`), mounts the
-   * bearer-gated grantee-facing provisioning surface at `/grants`
-   * (provision / peer / seed / terminate). Optional so callers/tests that don't
-   * exercise the donor path need not wire it.
-   */
-  donations?: DonationService;
-  /** Settings I/O facade. Defaults to a new one rooted at `dataDir`. */
-  settingsStore?: HostSettingsStore;
-  /** Bus instance — pass the same one to subsystems that publish events. */
-  events?: EventBus;
-  /**
-   * Static asset root override. Defaults to `<package>/dist/ui`. When the
-   * directory is absent the root handler returns a placeholder HTML.
-   */
-  staticRoot?: string;
-  /**
-   * Test-only: bind to port 0 (OS picks any free port). The returned URL
-   * reflects the actual bound port.
-   */
-  forcePort?: 0;
-  /**
-   * SSE heartbeat interval (ms). Defaults to 15 000 ms. Tests reduce this
-   * so the heartbeat can be observed quickly.
-   */
-  sseHeartbeatMs?: number;
-}
-
-export interface LocalUiServer {
-  app: FastifyInstance;
-  events: EventBus;
-  /** Resolves with the actually-bound port. */
-  start(): Promise<{ port: number; url: string }>;
-  stop(): Promise<void>;
-}
-
-/** How often to poll UpdateService.getState() looking for new versions. */
-const UPDATE_OBSERVER_INTERVAL_MS = 60_000;
-
-export function createLocalUiServer(opts: LocalUiServerOptions): LocalUiServer {
-  const { founder } = opts;
-  const role: HostRole = founder ? 'founder' : 'donor';
-  const events = opts.events ?? new EventBus();
-  const settingsStore = opts.settingsStore ?? new HostSettingsStore({ dataDir: opts.dataDir });
-
-  const app = buildFastify();
-
-  // Bound port is unknown until start(); the guard is registered then.
-
-  registerErrorHandler(app);
-
-  // /api/events (SSE) — must be registered before the static fallback so
-  // the not-found handler doesn't try to serve it.
-  registerSseRoute(app, {
-    events,
-    ...(opts.sseHeartbeatMs !== undefined ? { heartbeatIntervalMs: opts.sseHeartbeatMs } : {}),
-  });
-
-  registerStatusRoute(app, {
-    orchestrator: opts.orchestrator,
-    role,
-    ...(founder ? { trustCircle: founder.trustCircle, nat: founder.nat } : {}),
-    ...(opts.update ? { update: opts.update } : {}),
-  });
-  registerNodesRoutes(app, { orchestrator: opts.orchestrator, role });
-  registerSettingsRoutes(app, { settingsStore, ...(founder ? { nat: founder.nat } : {}), ...(opts.update ? { update: opts.update } : {}) });
-
-  // Trust-circle + NAT + strand surfaces exist only when the host runs its own
-  // personal cadre. In donor-only mode they're left unmounted, so `/auth/*`,
-  // `/nat/*` and `/api/strands` fall through to the static not-found handler and
-  // 404 (see static.ts).
-  if (founder) {
-    registerTrustCircleRoutes(app, { handlers: createTrustCircleHandlers(founder.trustCircle), events });
-    registerNatRoutes(app, { handlers: createNatHandlers(founder.nat), events });
-    registerStrandRoutes(app, { handlers: createStrandHandlers(founder.strands), events });
-  }
-  if (opts.update) {
-    registerUpdateRoutes(app, { handlers: createUpdateHandlers(opts.update), events });
-  }
-  if (opts.grants) {
-    registerGrantsAdminRoutes(app, { handlers: createGrantAdminHandlers(opts.grants, opts.donations), events });
-    // Grantee-facing provisioning surface needs both the donation service and a
-    // grant validator (the GrantService doubles as the validator).
-    if (opts.donations) {
-      registerGrantsRoutes(app, { donations: opts.donations, grants: opts.grants });
-    }
-  }
-
-  // Static mount registers as the not-found handler — declared last so the
-  // API paths above win.
-  registerStaticMount(app, { ...(opts.staticRoot !== undefined ? { rootDir: opts.staticRoot } : {}) });
-
-  let bound: { port: number; url: string } | null = null;
-  let stopped = false;
-  const teardown: Array<() => void> = [];
-
-  return {
-    app,
-    events,
-    async start() {
-      if (bound) return bound;
-      // Origin guard reads the port at request time via the getter so the
-      // post-fallback bound port is honoured. Registered here (not at
-      // factory time) so it lives in the same lifecycle as listen.
-      registerOriginGuard(app, { port: () => bound?.port ?? opts.uiPort });
-      const started = await startListening(app, {
-        preferredPort: opts.uiPort,
-        ...(opts.forcePort === 0 ? { forcePort: 0 as const } : {}),
-      });
-      bound = started;
-
-      // Orchestrator → bus adapter: forward node state changes.
-      teardown.push(
-        opts.orchestrator.onStateChange((info) => {
-          events.publish({
-            type: 'node-state-changed',
-            nodeId: info.id,
-            status: info.status === 'running' ? 'running' : 'stopped',
-          });
-        }),
-      );
-
-      // One-shot connectivity publish — the SPA will get a sane initial
-      // signal even if no settings have changed yet this session. Skipped in
-      // donor-only mode, where there is no NatService.
-      if (founder) {
-        try {
-          const snap = founder.nat.getStatus();
-          events.publish({
-            type: 'connectivity-changed',
-            portMode: snap.portMode,
-            directReachability: snap.directReachability,
-          });
-        } catch {
-          // NatService.start may not have completed; harmless to skip.
-        }
-      }
-
-      // Update observer: poll UpdateService.getState() every 60 s and emit
-      // `update-available` when `available.version` changes. Cheap, avoids
-      // poking at the service's internals.
-      if (opts.update) {
-        const update = opts.update;
-        let lastVersion: string | undefined;
-        const tick = async (): Promise<void> => {
-          try {
-            const state = await update.getState();
-            const available = state.available;
-            if (available && available.version && available.version !== lastVersion) {
-              lastVersion = available.version;
-              events.publish({
-                type: 'update-available',
-                version: available.version,
-                ...(available.releaseNotesUrl ? { releaseNotesUrl: available.releaseNotesUrl } : {}),
-              });
-            }
-          } catch {
-            // Update store I/O failure — silent, will retry next tick.
-          }
-        };
-        // Fire once on boot in case the timer set `available` before the server bound.
-        void tick();
-        const timer = setInterval(() => { void tick(); }, UPDATE_OBSERVER_INTERVAL_MS);
-        if (typeof timer === 'object' && 'unref' in timer) {
-          (timer as { unref?: () => void }).unref?.();
-        }
-        teardown.push(() => clearInterval(timer));
-      }
-
-      return started;
-    },
-    async stop() {
-      if (stopped) return;
-      stopped = true;
-      for (const fn of teardown.splice(0, teardown.length)) {
-        try { fn(); } catch { /* ignore teardown errors */ }
-      }
-      await stopListening(app);
-    },
-  };
-}
-
-export { EventBus } from './events/bus.js';
-export type { LocalUiEventListener } from './events/bus.js';
-export type { LocalUiEvent, LocalUiEventType } from './events/types.js';
-export { HostSettingsStore } from './settings-store.js';
-export type { HostRole } from './routes/status.js';
+/**
+ * Public surface for the cadre-host local UI server.
+ *
+ * `createLocalUiServer(opts)` wires:
+ *   - the origin guard + error handler
+ *   - existing NAT / update typed handlers, mounted at `/nat/*`, `/update/*`
+ *     (the CLI contract)
+ *   - the `/api/*` routes (status, nodes, hosted nodes, settings, events)
+ *   - the static SPA mount at `/`
+ *
+ * Callers (cadre-host start) own the subsystems and pass them in. The
+ * server doesn't construct them — start has to own their lifecycle anyway
+ * (orchestrator init, NAT bring-up, update timer).
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { HostProcessOrchestrator } from '../orchestrator/index.js';
+import type { NatService } from '../nat/index.js';
+import { createNatHandlers } from '../nat/index.js';
+import type { UpdateService } from '../update/index.js';
+import { createUpdateHandlers } from '../update/index.js';
+import type { HostedNodeService } from '../hosted/index.js';
+
+import { EventBus } from './events/bus.js';
+import { registerSseRoute } from './events/sse-route.js';
+import { registerErrorHandler } from './error-handler.js';
+import { registerOriginGuard } from './origin-guard.js';
+import { registerStaticMount } from './static.js';
+import { buildFastify, startListening, stopListening } from './server.js';
+import { registerNatRoutes, publishConnectivity } from './routes/nat.js';
+import { registerUpdateRoutes } from './routes/update.js';
+import { registerStatusRoute } from './routes/status.js';
+import { registerNodesRoutes } from './routes/nodes.js';
+import { registerSettingsRoutes } from './routes/settings.js';
+import { registerHostedNodesRoutes } from './routes/hosted-nodes.js';
+import { HostSettingsStore } from './settings-store.js';
+
+export interface LocalUiServerOptions {
+  /** Configured UI port from host.config.json. May be re-bound on collision. */
+  uiPort: number;
+  /** Resolved data dir (passed by cadre-host start). */
+  dataDir: string;
+  /** Wired dependencies — all owned by the caller. */
+  orchestrator: HostProcessOrchestrator;
+  /** The NAT layer: every node the host runs gets its ports mapped, so `/nat/*` always mounts. */
+  nat: NatService;
+  /** Optional — 6.4.2 lands this; nullable while still iterating. */
+  update?: UpdateService;
+  /**
+   * The hosted-node service. When present, mounts `/api/hosted-nodes` and
+   * forwards the service's changes to the bus as `hosted-nodes-changed`.
+   * Optional so callers/tests that don't exercise hosted nodes need not wire it.
+   */
+  hostedNodes?: HostedNodeService;
+  /** Settings I/O facade. Defaults to a new one rooted at `dataDir`. */
+  settingsStore?: HostSettingsStore;
+  /** Bus instance — pass the same one to subsystems that publish events. */
+  events?: EventBus;
+  /**
+   * Static asset root override. Defaults to `<package>/dist/ui`. When the
+   * directory is absent the root handler returns a placeholder HTML.
+   */
+  staticRoot?: string;
+  /**
+   * Test-only: bind to port 0 (OS picks any free port). The returned URL
+   * reflects the actual bound port.
+   */
+  forcePort?: 0;
+  /**
+   * SSE heartbeat interval (ms). Defaults to 15 000 ms. Tests reduce this
+   * so the heartbeat can be observed quickly.
+   */
+  sseHeartbeatMs?: number;
+}
+
+export interface LocalUiServer {
+  app: FastifyInstance;
+  events: EventBus;
+  /** Resolves with the actually-bound port. */
+  start(): Promise<{ port: number; url: string }>;
+  stop(): Promise<void>;
+}
+
+/** How often to poll UpdateService.getState() looking for new versions. */
+const UPDATE_OBSERVER_INTERVAL_MS = 60_000;
+
+export function createLocalUiServer(opts: LocalUiServerOptions): LocalUiServer {
+  const { nat } = opts;
+  const events = opts.events ?? new EventBus();
+  const settingsStore = opts.settingsStore ?? new HostSettingsStore({ dataDir: opts.dataDir });
+
+  const app = buildFastify();
+
+  // Bound port is unknown until start(); the guard is registered then.
+
+  registerErrorHandler(app);
+
+  // /api/events (SSE) — must be registered before the static fallback so
+  // the not-found handler doesn't try to serve it.
+  registerSseRoute(app, {
+    events,
+    ...(opts.sseHeartbeatMs !== undefined ? { heartbeatIntervalMs: opts.sseHeartbeatMs } : {}),
+  });
+
+  registerStatusRoute(app, {
+    orchestrator: opts.orchestrator,
+    nat,
+    ...(opts.update ? { update: opts.update } : {}),
+  });
+  registerNodesRoutes(app, { orchestrator: opts.orchestrator });
+  registerSettingsRoutes(app, { settingsStore, nat, ...(opts.update ? { update: opts.update } : {}) });
+  registerNatRoutes(app, { handlers: createNatHandlers(nat), events });
+  if (opts.update) {
+    registerUpdateRoutes(app, { handlers: createUpdateHandlers(opts.update), events });
+  }
+  if (opts.hostedNodes) {
+    registerHostedNodesRoutes(app, { hostedNodes: opts.hostedNodes });
+  }
+
+  // Static mount registers as the not-found handler — declared last so the
+  // API paths above win.
+  registerStaticMount(app, { ...(opts.staticRoot !== undefined ? { rootDir: opts.staticRoot } : {}) });
+
+  let bound: { port: number; url: string } | null = null;
+  let stopped = false;
+  const teardown: Array<() => void> = [];
+
+  return {
+    app,
+    events,
+    async start() {
+      if (bound) return bound;
+      // Origin guard reads the port at request time via the getter so the
+      // post-fallback bound port is honoured. Registered here (not at
+      // factory time) so it lives in the same lifecycle as listen.
+      registerOriginGuard(app, { port: () => bound?.port ?? opts.uiPort });
+      const started = await startListening(app, {
+        preferredPort: opts.uiPort,
+        ...(opts.forcePort === 0 ? { forcePort: 0 as const } : {}),
+      });
+      bound = started;
+
+      // Orchestrator → bus adapter: forward node state changes.
+      teardown.push(
+        opts.orchestrator.onStateChange((info) => {
+          events.publish({
+            type: 'node-state-changed',
+            nodeId: info.id,
+            status: info.status === 'running' ? 'running' : 'stopped',
+          });
+        }),
+      );
+
+      // NAT → bus adapter: a mapping that completes after a spawn, an IP change
+      // or a lease the router dropped all change the snapshot without any
+      // route being called; the SPA follows them through this.
+      teardown.push(nat.onChange((snap) => { publishConnectivity(events, snap); }));
+
+      // Hosted nodes → bus adapter: a join, a claim the watcher noticed, a
+      // removal, a respawn or a give-up — the routes publish nothing themselves.
+      if (opts.hostedNodes) {
+        teardown.push(opts.hostedNodes.onChange((change) => {
+          events.publish({ type: 'hosted-nodes-changed', kind: change.kind, nodeId: change.id });
+        }));
+      }
+
+      // One-shot connectivity publish — the SPA will get a sane initial
+      // signal even if no settings have changed yet this session.
+      try {
+        publishConnectivity(events, nat.getStatus());
+      } catch {
+        // NatService.start may not have completed; harmless to skip.
+      }
+
+      // Update observer: poll UpdateService.getState() every 60 s and emit
+      // `update-available` when `available.version` changes. Cheap, avoids
+      // poking at the service's internals.
+      if (opts.update) {
+        const update = opts.update;
+        let lastVersion: string | undefined;
+        const tick = async (): Promise<void> => {
+          try {
+            const state = await update.getState();
+            const available = state.available;
+            if (available && available.version && available.version !== lastVersion) {
+              lastVersion = available.version;
+              events.publish({
+                type: 'update-available',
+                version: available.version,
+                ...(available.releaseNotesUrl ? { releaseNotesUrl: available.releaseNotesUrl } : {}),
+              });
+            }
+          } catch {
+            // Update store I/O failure — silent, will retry next tick.
+          }
+        };
+        // Fire once on boot in case the timer set `available` before the server bound.
+        void tick();
+        const timer = setInterval(() => { void tick(); }, UPDATE_OBSERVER_INTERVAL_MS);
+        if (typeof timer === 'object' && 'unref' in timer) {
+          (timer as { unref?: () => void }).unref?.();
+        }
+        teardown.push(() => clearInterval(timer));
+      }
+
+      return started;
+    },
+    async stop() {
+      if (stopped) return;
+      stopped = true;
+      for (const fn of teardown.splice(0, teardown.length)) {
+        try { fn(); } catch { /* ignore teardown errors */ }
+      }
+      await stopListening(app);
+    },
+  };
+}
+
+export { EventBus } from './events/bus.js';
+export type { LocalUiEventListener } from './events/bus.js';
+export type { LocalUiEvent, LocalUiEventType } from './events/types.js';
+export { HostSettingsStore } from './settings-store.js';

package/src/server/routes/hosted-nodes.ts

@@ -0,0 +1,83 @@
+/**
+ * `/api/hosted-nodes` — the host's "Join a cadre" action and the nodes it made.
+ * Loopback, no bearer: same-machine admin, matching the local-UI "no login"
+ * posture. Clients: the `cadre-host join` / `cadre-host node` CLI and the local
+ * UI.
+ *
+ *   GET    /api/hosted-nodes            every hosted node (secret and invitation stripped)
+ *   POST   /api/hosted-nodes            { invitation? } start a node waiting to be claimed, or one
+ *                                       that redeems the invitation → 201 { node }
+ *   GET    /api/hosted-nodes/:id        one node
+ *   GET    /api/hosted-nodes/:id/claim  the QR payload: 409 unless unclaimed, 503 until the child answers
+ *   DELETE /api/hosted-nodes/:id        stop the node and delete its data → 204
+ *   POST   /api/hosted-nodes/:id/reset  remove, then start a fresh node → 201 { node }
+ *   POST   /api/hosted-nodes/:id/retry  start an invitation node again after no member
+ *                                       could be reached → { node }; 409 unless so
+ *
+ * Responses use the `/api/*` envelope (`{ ok, data }`); errors come from
+ * `HostedNodeError`, which `server/error-handler.ts` maps. The mutations publish
+ * nothing themselves: the service reports every change through its listener,
+ * which `server/index.ts` wires to the bus as `hosted-nodes-changed`, so a
+ * change the watcher or the supervisor makes reaches the SPA the same way.
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { HostedNodeService, JoinOptions } from '../../hosted/hosted-node-service.js';
+import { HostedNodeError } from '../../hosted/types.js';
+
+export interface HostedNodesRoutesOptions {
+  hostedNodes: HostedNodeService;
+}
+
+export function registerHostedNodesRoutes(app: FastifyInstance, opts: HostedNodesRoutesOptions): void {
+  const { hostedNodes } = opts;
+
+  app.get('/api/hosted-nodes', async () => {
+    return { ok: true, data: { nodes: hostedNodes.list() } };
+  });
+
+  app.post('/api/hosted-nodes', async (request, reply) => {
+    const node = await hostedNodes.join(joinOptionsOf(request.body));
+    return reply.status(201).send({ ok: true, data: { node } });
+  });
+
+  app.get<{ Params: { id: string } }>('/api/hosted-nodes/:id', async (request, reply) => {
+    const node = hostedNodes.get(request.params.id);
+    if (!node) {
+      return reply.status(404).send({ ok: false, error: { code: 'not_found', message: `No such hosted node: ${request.params.id}` } });
+    }
+    return { ok: true, data: { node } };
+  });
+
+  app.get<{ Params: { id: string } }>('/api/hosted-nodes/:id/claim', async (request) => {
+    return { ok: true, data: await hostedNodes.claimDetails(request.params.id) };
+  });
+
+  app.delete<{ Params: { id: string } }>('/api/hosted-nodes/:id', async (request, reply) => {
+    await hostedNodes.remove(request.params.id);
+    return reply.status(204).send();
+  });
+
+  app.post<{ Params: { id: string } }>('/api/hosted-nodes/:id/reset', async (request, reply) => {
+    const node = await hostedNodes.reset(request.params.id);
+    return reply.status(201).send({ ok: true, data: { node } });
+  });
+
+  app.post<{ Params: { id: string } }>('/api/hosted-nodes/:id/retry', async (request) => {
+    return { ok: true, data: { node: await hostedNodes.retry(request.params.id) } };
+  });
+}
+
+/** The join body: none (or `{}`) for a node waiting to be claimed, `{ invitation }` for one that redeems it. */
+function joinOptionsOf(body: unknown): JoinOptions {
+  const fields = (body ?? {}) as { invitation?: unknown };
+  if (typeof fields !== 'object' || Array.isArray(fields)) {
+    throw new HostedNodeError('invalid_request', 'The body must be a JSON object');
+  }
+  if (fields.invitation === undefined) return {};
+  if (typeof fields.invitation !== 'string' || fields.invitation.trim() === '') {
+    throw new HostedNodeError('invalid_request', '`invitation` must be the invitation text the owner\'s app copied');
+  }
+  return { invitation: fields.invitation };
+}