@serfab/cadre-host 1.13.0 → 1.14.0

package/src/server/__tests__/status-route.test.ts

@@ -1,121 +1,82 @@
-import Fastify from 'fastify';
-import { describe, it, expect, afterEach } from 'vitest';
-
-import { registerErrorHandler } from '../error-handler.js';
-import { registerStatusRoute } from '../routes/status.js';
-import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
-import type { ManagedNodeInfo } from '../../orchestrator/types.js';
-import type { TrustCircleService } from '../../auth/index.js';
-import type { TrustCircleSnapshot } from '../../auth/types.js';
-import type { NatService } from '../../nat/index.js';
-import type { NatStatusSnapshot } from '../../nat/types.js';
-import type { UpdateService } from '../../update/index.js';
-import type { UpdateState } from '../../update/types.js';
-import { SAMPLE_CONNECTIVITY } from './fakes.js';
-
-function fakeOrchestrator(nodes: ManagedNodeInfo[]): HostProcessOrchestrator {
-  return { listNodes: () => nodes } as unknown as HostProcessOrchestrator;
-}
-function fakeTrustCircle(snap: TrustCircleSnapshot): TrustCircleService {
-  return { list: async () => snap } as unknown as TrustCircleService;
-}
-function fakeNat(snap: NatStatusSnapshot): NatService {
-  return { getStatus: () => snap } as unknown as NatService;
-}
-function fakeUpdate(state: UpdateState): UpdateService {
-  return { getState: async () => state } as unknown as UpdateService;
-}
-
-describe('GET /api/status', () => {
-  let app: ReturnType<typeof Fastify>;
-
-  afterEach(async () => { await app.close(); });
-
-  it('returns aggregated status without update service', async () => {
-    app = Fastify();
-    registerErrorHandler(app);
-    registerStatusRoute(app, {
-      role: 'founder',
-      orchestrator: fakeOrchestrator([
-        {
-          id: 'alice',
-          dockerId: '1234:abc',
-          partyId: 'party-alice',
-          profile: 'storage',
-          status: 'running',
-          spawnedAt: '2025-01-01T00:00:00Z',
-          workdir: '/tmp/alice',
-          ports: { health: 1, metrics: 2, p2p: 3, admin: 4, ws: 5 },
-        },
-      ]),
-      trustCircle: fakeTrustCircle({
-        members: [{ peerId: 'p1', label: 'Self', addedAt: '2025-01-01T00:00:00Z', self: true }],
-        pending: [],
-      }),
-      nat: fakeNat(SAMPLE_CONNECTIVITY),
-    });
-
-    const res = await app.inject({ method: 'GET', url: '/api/status' });
-    expect(res.statusCode).toBe(200);
-    const body = res.json() as {
-      service: { name: string; version: string; uptimeSeconds: number };
-      role: string;
-      nodes: Array<{ id: string; status: string }>;
-      trustCircle: { members: number; pending: number };
-      connectivity: { portMode: string };
-      update?: { available?: string };
-    };
-    expect(body.service.name).toBe('cadre-host');
-    expect(body.role).toBe('founder');
-    expect(body.nodes).toHaveLength(1);
-    expect(body.nodes[0]).toMatchObject({ id: 'alice', status: 'running' });
-    expect(body.trustCircle).toEqual({ members: 1, pending: 0 });
-    expect(body.connectivity.portMode).toBe('auto-upnp');
-    expect(body.update).toBeUndefined();
-  });
-
-  it('omits trustCircle + connectivity in donor-only mode (no trust circle / NAT wired)', async () => {
-    app = Fastify();
-    registerErrorHandler(app);
-    registerStatusRoute(app, {
-      role: 'donor',
-      orchestrator: fakeOrchestrator([]),
-    });
-
-    const res = await app.inject({ method: 'GET', url: '/api/status' });
-    expect(res.statusCode).toBe(200);
-    const body = res.json() as {
-      service: { name: string };
-      role: string;
-      nodes: unknown[];
-      trustCircle?: unknown;
-      connectivity?: unknown;
-    };
-    expect(body.service.name).toBe('cadre-host');
-    expect(body.role).toBe('donor');
-    expect(body.nodes).toEqual([]);
-    expect(body.trustCircle).toBeUndefined();
-    expect(body.connectivity).toBeUndefined();
-  });
-
-  it('includes update info when service is present', async () => {
-    app = Fastify();
-    registerErrorHandler(app);
-    registerStatusRoute(app, {
-      role: 'founder',
-      orchestrator: fakeOrchestrator([]),
-      trustCircle: fakeTrustCircle({ members: [], pending: [] }),
-      nat: fakeNat(SAMPLE_CONNECTIVITY),
-      update: fakeUpdate({
-        version: 1,
-        lastChecked: '2025-06-01T00:00:00Z',
-        available: { version: '0.7.0', publishedAt: '2025-06-01T00:00:00Z' },
-      }),
-    });
-
-    const res = await app.inject({ method: 'GET', url: '/api/status' });
-    expect(res.statusCode).toBe(200);
-    const body = res.json() as { update?: { available?: string; lastChecked?: string } };
-    expect(body.update).toEqual({ available: '0.7.0', lastChecked: '2025-06-01T00:00:00Z' });
-  });
-});
+import Fastify from 'fastify';
+import { describe, it, expect, afterEach } from 'vitest';
+
+import { registerErrorHandler } from '../error-handler.js';
+import { registerStatusRoute } from '../routes/status.js';
+import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
+import type { ManagedNodeInfo } from '../../orchestrator/types.js';
+import type { NatService } from '../../nat/index.js';
+import type { NatStatusSnapshot } from '../../nat/types.js';
+import type { UpdateService } from '../../update/index.js';
+import type { UpdateState } from '../../update/types.js';
+import { SAMPLE_CONNECTIVITY } from './fakes.js';
+
+function fakeOrchestrator(nodes: ManagedNodeInfo[]): HostProcessOrchestrator {
+  return { listNodes: () => nodes } as unknown as HostProcessOrchestrator;
+}
+function fakeNat(snap: NatStatusSnapshot): NatService {
+  return { getStatus: () => snap } as unknown as NatService;
+}
+function fakeUpdate(state: UpdateState): UpdateService {
+  return { getState: async () => state } as unknown as UpdateService;
+}
+
+describe('GET /api/status', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  afterEach(async () => { await app.close(); });
+
+  it('returns aggregated status without update service', async () => {
+    app = Fastify();
+    registerErrorHandler(app);
+    registerStatusRoute(app, {
+      orchestrator: fakeOrchestrator([
+        {
+          id: 'alice',
+          dockerId: '1234:abc',
+          partyId: 'party-alice',
+          profile: 'storage',
+          status: 'running',
+          spawnedAt: '2025-01-01T00:00:00Z',
+          workdir: '/tmp/alice',
+          ports: { health: 1, metrics: 2, p2p: 3, ws: 5 },
+          announcedAddrs: [],
+        },
+      ]),
+      nat: fakeNat(SAMPLE_CONNECTIVITY),
+    });
+
+    const res = await app.inject({ method: 'GET', url: '/api/status' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      service: { name: string; version: string; uptimeSeconds: number };
+      nodes: Array<{ id: string; status: string }>;
+      connectivity: { directReachability: string };
+      update?: { available?: string };
+    };
+    expect(body.service.name).toBe('cadre-host');
+    expect(body.nodes).toHaveLength(1);
+    expect(body.nodes[0]).toMatchObject({ id: 'alice', status: 'running' });
+    expect(body.connectivity.directReachability).toBe('reachable');
+    expect(body.update).toBeUndefined();
+  });
+
+  it('includes update info when service is present', async () => {
+    app = Fastify();
+    registerErrorHandler(app);
+    registerStatusRoute(app, {
+      orchestrator: fakeOrchestrator([]),
+      nat: fakeNat(SAMPLE_CONNECTIVITY),
+      update: fakeUpdate({
+        version: 1,
+        lastChecked: '2025-06-01T00:00:00Z',
+        available: { version: '0.7.0', publishedAt: '2025-06-01T00:00:00Z' },
+      }),
+    });
+
+    const res = await app.inject({ method: 'GET', url: '/api/status' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { update?: { available?: string; lastChecked?: string } };
+    expect(body.update).toEqual({ available: '0.7.0', lastChecked: '2025-06-01T00:00:00Z' });
+  });
+});

package/src/server/error-handler.ts

@@ -1,178 +1,112 @@
-/**
- * Fastify error handler — translates known typed errors to stable HTTP status
- * codes and uniform `{ ok: false, error: { code, message } }` payloads.
- *
- * Codes (cross-referenced with `auth/types.ts`, `nat/types.ts`, `strands/types.ts`,
- * `update/types.ts`):
- *   - TrustCircleError
- *       invalid_label, invalid_token             → 400
- *       not_found, already_redeemed              → 404
- *       expired                                  → 410
- *       node_unavailable                         → 503
- *       storage_error                            → 500
- *   - NatError
- *       invalid_config, ddns_provider_unknown,
- *       ddns_credentials_missing                 → 400
- *       secrets_unavailable, storage_error,
- *       mapping_failed, router_unreachable,
- *       ip_detection_failed, ddns_update_failed  → 500
- *       node_unavailable                         → 503
- *   - StrandError
- *       invalid_id                               → 400
- *       confirmation_required                    → 428
- *       node_unavailable                         → 503
- *       internal                                 → 500
- *   - UpdateErrorException
- *       manifest_invalid, no_update_available,
- *       min_previous_version                     → 400
- *       apply_in_progress                        → 409
- *       signature_invalid, unsupported_state_version,
- *       apply_failed, rollback_failed, storage_error → 500
- *   - GrantError
- *       invalid_label, invalid_max_nodes,
- *       invalid_ttl                              → 400
- *       not_found                                → 404
- *       storage_error                            → 500
- *   - DonationError
- *       invalid_request                          → 400
- *       unauthorized                             → 401
- *       forbidden                                → 403
- *       not_found                                → 404
- *       invalid_state                            → 409
- *       quota_exceeded                           → 429
- *       orchestrator_error, storage_error        → 500
- *       seed_failed                              → 502
- *       peer_unavailable                         → 503
- *   - everything else                            → 500 (code "internal")
- */
-
-import type { FastifyError, FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
-import debug from 'debug';
-
-import { TrustCircleError, type TrustCircleErrorCode } from '../auth/types.js';
-import { NatError, type NatErrorCode } from '../nat/types.js';
-import { StrandError, type StrandErrorCode } from '../strands/types.js';
-import { UpdateErrorException, type UpdateErrorCode } from '../update/types.js';
-import { GrantError, type GrantErrorCode, DonationError, type DonationErrorCode } from '../donation/types.js';
-
-const log = debug('cadre:host:error-handler');
-
-const TRUST_STATUS: Record<TrustCircleErrorCode, number> = {
-  invalid_label: 400,
-  invalid_token: 400,
-  not_found: 404,
-  already_redeemed: 404,
-  expired: 410,
-  storage_error: 500,
-  node_unavailable: 503,
-};
-
-const NAT_STATUS: Record<NatErrorCode, number> = {
-  invalid_config: 400,
-  ddns_provider_unknown: 400,
-  ddns_credentials_missing: 400,
-  secrets_unavailable: 500,
-  storage_error: 500,
-  mapping_failed: 500,
-  router_unreachable: 500,
-  ip_detection_failed: 500,
-  ddns_update_failed: 500,
-  node_unavailable: 503,
-};
-
-/**
- * 428 (Precondition Required) for `confirmation_required`: the node refused a
- * closed-strand removal because the caller had not confirmed. It is not a 400
- * (the request was well-formed) and not a 409 (nothing conflicts) — the caller
- * must re-send with the precondition satisfied.
- */
-const STRAND_STATUS: Record<StrandErrorCode, number> = {
-  invalid_id: 400,
-  confirmation_required: 428,
-  node_unavailable: 503,
-  internal: 500,
-};
-
-const GRANT_STATUS: Record<GrantErrorCode, number> = {
-  invalid_label: 400,
-  invalid_max_nodes: 400,
-  invalid_ttl: 400,
-  not_found: 404,
-  storage_error: 500,
-};
-
-const DONATION_STATUS: Record<DonationErrorCode, number> = {
-  unauthorized: 401,
-  forbidden: 403,
-  quota_exceeded: 429,
-  invalid_request: 400,
-  not_found: 404,
-  invalid_state: 409,
-  seed_failed: 502,
-  peer_unavailable: 503,
-  orchestrator_error: 500,
-  storage_error: 500,
-};
-
-const UPDATE_STATUS: Record<UpdateErrorCode, number> = {
-  manifest_invalid: 400,
-  no_update_available: 400,
-  min_previous_version: 400,
-  apply_in_progress: 409,
-  signature_invalid: 500,
-  unsupported_state_version: 500,
-  apply_failed: 500,
-  rollback_failed: 500,
-  storage_error: 500,
-};
-
-export function registerErrorHandler(app: FastifyInstance): void {
-  app.setErrorHandler((err: FastifyError, request: FastifyRequest, reply: FastifyReply) => {
-    const { status, code, message } = classify(err);
-    if (status >= 500) {
-      log('5xx %s %s: [%s] %s', request.method, request.url, code, message);
-    } else {
-      log('%d %s %s: [%s] %s', status, request.method, request.url, code, message);
-    }
-    return reply.code(status).send({
-      ok: false,
-      error: { code, message },
-    });
-  });
-}
-
-interface Classified {
-  status: number;
-  code: string;
-  message: string;
-}
-
-function classify(err: FastifyError): Classified {
-  if (err instanceof TrustCircleError) {
-    return { status: TRUST_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof NatError) {
-    return { status: NAT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof StrandError) {
-    return { status: STRAND_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof UpdateErrorException) {
-    return { status: UPDATE_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof GrantError) {
-    return { status: GRANT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof DonationError) {
-    return { status: DONATION_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  // Fastify body-parsing / validation errors have a statusCode we should honour.
-  if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600) {
-    return {
-      status: err.statusCode,
-      code: err.code ?? (err.statusCode === 404 ? 'not_found' : 'bad_request'),
-      message: err.message ?? 'request failed',
-    };
-  }
-  return { status: 500, code: 'internal', message: err.message || 'internal error' };
-}
+/**
+ * Fastify error handler — translates known typed errors to stable HTTP status
+ * codes and uniform `{ ok: false, error: { code, message } }` payloads.
+ *
+ * Codes (cross-referenced with `nat/types.ts`, `update/types.ts`,
+ * `hosted/types.ts`):
+ *   - NatError
+ *       invalid_config, ddns_provider_unknown,
+ *       ddns_credentials_missing                 → 400
+ *       unknown_node                             → 404
+ *       secrets_unavailable, storage_error,
+ *       mapping_failed, router_unreachable,
+ *       ip_detection_failed, ddns_update_failed  → 500
+ *   - UpdateErrorException
+ *       manifest_invalid, no_update_available,
+ *       min_previous_version                     → 400
+ *       apply_in_progress                        → 409
+ *       signature_invalid, unsupported_state_version,
+ *       apply_failed, rollback_failed, storage_error → 500
+ *   - HostedNodeError
+ *       invalid_request                          → 400
+ *       not_found                                → 404
+ *       invalid_state                            → 409
+ *       orchestrator_error, storage_error        → 500
+ *       node_unavailable                         → 503
+ *   - everything else                            → 500 (code "internal")
+ */
+
+import type { FastifyError, FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import debug from 'debug';
+
+import { NatError, type NatErrorCode } from '../nat/types.js';
+import { UpdateErrorException, type UpdateErrorCode } from '../update/types.js';
+import { HostedNodeError, type HostedNodeErrorCode } from '../hosted/types.js';
+
+const log = debug('cadre:host:error-handler');
+
+const NAT_STATUS: Record<NatErrorCode, number> = {
+  invalid_config: 400,
+  ddns_provider_unknown: 400,
+  ddns_credentials_missing: 400,
+  unknown_node: 404,
+  secrets_unavailable: 500,
+  storage_error: 500,
+  mapping_failed: 500,
+  router_unreachable: 500,
+  ip_detection_failed: 500,
+  ddns_update_failed: 500,
+};
+
+const HOSTED_NODE_STATUS: Record<HostedNodeErrorCode, number> = {
+  invalid_request: 400,
+  not_found: 404,
+  invalid_state: 409,
+  node_unavailable: 503,
+  orchestrator_error: 500,
+  storage_error: 500,
+};
+
+const UPDATE_STATUS: Record<UpdateErrorCode, number> = {
+  manifest_invalid: 400,
+  no_update_available: 400,
+  min_previous_version: 400,
+  apply_in_progress: 409,
+  signature_invalid: 500,
+  unsupported_state_version: 500,
+  apply_failed: 500,
+  rollback_failed: 500,
+  storage_error: 500,
+};
+
+export function registerErrorHandler(app: FastifyInstance): void {
+  app.setErrorHandler((err: FastifyError, request: FastifyRequest, reply: FastifyReply) => {
+    const { status, code, message } = classify(err);
+    if (status >= 500) {
+      log('5xx %s %s: [%s] %s', request.method, request.url, code, message);
+    } else {
+      log('%d %s %s: [%s] %s', status, request.method, request.url, code, message);
+    }
+    return reply.code(status).send({
+      ok: false,
+      error: { code, message },
+    });
+  });
+}
+
+interface Classified {
+  status: number;
+  code: string;
+  message: string;
+}
+
+function classify(err: FastifyError): Classified {
+  if (err instanceof NatError) {
+    return { status: NAT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof UpdateErrorException) {
+    return { status: UPDATE_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof HostedNodeError) {
+    return { status: HOSTED_NODE_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  // Fastify body-parsing / validation errors have a statusCode we should honour.
+  if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600) {
+    return {
+      status: err.statusCode,
+      code: err.code ?? (err.statusCode === 404 ? 'not_found' : 'bad_request'),
+      message: err.message ?? 'request failed',
+    };
+  }
+  return { status: 500, code: 'internal', message: err.message || 'internal error' };
+}

package/src/server/events/types.ts

@@ -1,24 +1,20 @@
-/**
- * Event types broadcast over the SPA's SSE channel.
- *
- * Publishers (orchestrator hook, route adapters, update observer) call
- * EventBus.publish; the `/api/events` route fan-outs to connected clients.
- */
-
-import type { ContainerStatus } from '@serfab/cadre-provider';
-
-import type { DirectReachability, PortForwardMode } from '../../nat/index.js';
-
-export type LocalUiEvent =
-  | { type: 'node-state-changed'; nodeId: string; status: ContainerStatus }
-  | { type: 'trust-circle-changed'; kind: 'invited' | 'redeemed' | 'revoked' }
-  | { type: 'strands-changed'; kind: 'removed' }
-  | { type: 'grants-changed'; kind: 'issued' | 'revoked' | 'terminated' }
-  | {
-      type: 'connectivity-changed';
-      portMode: PortForwardMode;
-      directReachability: DirectReachability;
-    }
-  | { type: 'update-available'; version: string; releaseNotesUrl?: string };
-
-export type LocalUiEventType = LocalUiEvent['type'];
+/**
+ * Event types broadcast over the SPA's SSE channel.
+ *
+ * Publishers (orchestrator hook, route adapters, NAT change listener, the
+ * hosted-node service's change listener, update observer) call
+ * EventBus.publish; the `/api/events` route fan-outs to connected clients.
+ */
+
+import type { ContainerStatus } from '@serfab/cadre-provider';
+
+import type { HostedNodeChangeKind } from '../../hosted/types.js';
+import type { DirectReachability } from '../../nat/index.js';
+
+export type LocalUiEvent =
+  | { type: 'node-state-changed'; nodeId: string; status: ContainerStatus }
+  | { type: 'hosted-nodes-changed'; kind: HostedNodeChangeKind; nodeId: string }
+  | { type: 'connectivity-changed'; directReachability: DirectReachability }
+  | { type: 'update-available'; version: string; releaseNotesUrl?: string };
+
+export type LocalUiEventType = LocalUiEvent['type'];