@serfab/cadre-host 0.7.1

package/src/orchestrator/port-allocator.ts

@@ -0,0 +1,43 @@
+/**
+ * Range-based port tracker. Allocations are in-memory; on orchestrator
+ * restart the caller rehydrates the used-set from persisted state via
+ * `markUsed(port)` before serving new allocations.
+ */
+export class PortAllocator {
+  private readonly usedPorts = new Set<number>();
+
+  constructor(
+    private readonly start: number,
+    private readonly end: number,
+  ) {
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start <= 0 || end < start) {
+      throw new Error(`Invalid port range: ${start}..${end}`);
+    }
+  }
+
+  allocate(): number {
+    for (let port = this.start; port <= this.end; port++) {
+      if (!this.usedPorts.has(port)) {
+        this.usedPorts.add(port);
+        return port;
+      }
+    }
+    throw new Error(`No available ports in range ${this.start}..${this.end}`);
+  }
+
+  release(port: number): void {
+    this.usedPorts.delete(port);
+  }
+
+  /** Used during restart rehydration to reserve ports already in use. */
+  markUsed(port: number): void {
+    if (port < this.start || port > this.end) {
+      return;
+    }
+    this.usedPorts.add(port);
+  }
+
+  has(port: number): boolean {
+    return this.usedPorts.has(port);
+  }
+}

package/src/orchestrator/state-store.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+
+const log = debug('cadre:host:state-store');
+
+/**
+ * Persisted record for a single managed child. The orchestrator mirrors its
+ * in-memory map to disk so that cadre-host can re-attach to surviving
+ * children after a restart.
+ */
+export interface PersistedHandle {
+  containerId: string;        // provider-assigned ID, passed in createContainer
+  dockerId: string;           // opaque token returned to callers (encoded "pid:token")
+  pid: number;
+  startupToken: string;
+  workdir: string;
+  ports: { health: number; metrics: number; p2p: number };
+  spawnedAt: string;          // ISO timestamp
+  partyId: string;
+  profile: 'storage' | 'transaction';
+}
+
+export interface PersistedState {
+  version: 1;
+  handles: PersistedHandle[];
+}
+
+const STATE_VERSION = 1;
+
+/** JSON state file at `<rootDir>/state.json`, written atomically. */
+export class StateStore {
+  private readonly path: string;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, 'state.json');
+  }
+
+  load(): PersistedState {
+    if (!existsSync(this.path)) {
+      return { version: STATE_VERSION, handles: [] };
+    }
+    try {
+      const raw = readFileSync(this.path, 'utf8');
+      const parsed = JSON.parse(raw) as PersistedState;
+      if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.handles)) {
+        log('state file at %s has unexpected shape; treating as empty', this.path);
+        return { version: STATE_VERSION, handles: [] };
+      }
+      return { version: STATE_VERSION, handles: parsed.handles };
+    } catch (err) {
+      // A corrupt state file is operationally significant — surviving children
+      // may now be leaked to the OS without an in-memory handle. Make the
+      // failure visible rather than silently returning empty.
+      log('failed to load state file at %s: %o', this.path, err);
+      return { version: STATE_VERSION, handles: [] };
+    }
+  }
+
+  save(state: PersistedState): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const payload = JSON.stringify({ version: STATE_VERSION, handles: state.handles }, null, 2);
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8' });
+    renameSync(tmp, this.path);
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+}

package/src/orchestrator/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Public + internal types for the HostProcessOrchestrator.
+ */
+
+import type { ChildProcess } from 'node:child_process';
+
+/** User-facing configuration for `HostProcessOrchestrator`. */
+export interface HostProcessConfig {
+  /** Root directory under which per-container workdirs live. */
+  rootDir: string;
+  /** Port allocation range (default 10000..20000). */
+  portRange?: { start: number; end: number };
+  /** Default resource limits (memory only in v1). */
+  defaultResources?: { memoryLimit?: string };
+  /** SIGTERM → SIGKILL grace period (default 10000 ms). */
+  stopTimeoutMs?: number;
+  /** Log rotation: bytes per file (default 10 MB). */
+  logMaxBytes?: number;
+  /** Log rotation: max rotated files (default 5). */
+  logMaxFiles?: number;
+  /**
+   * Test-only hook: override the child entrypoint. When set, the orchestrator
+   * spawns `node <entrypoint> ...` instead of resolving `@serfab/cadre-cli`.
+   */
+  spawn?: { entrypoint?: string };
+}
+
+/** In-memory record per managed child. */
+export interface Handle {
+  containerId: string;
+  dockerId: string;
+  pid: number;
+  startupToken: string;
+  workdir: string;
+  ports: { health: number; metrics: number; p2p: number };
+  spawnedAt: string;
+  partyId: string;
+  profile: 'storage' | 'transaction';
+  /** Live ChildProcess reference; absent after re-attach via init(). */
+  child?: ChildProcess;
+  /** Marked false when init() finds the PID dead or token mismatched. */
+  alive: boolean;
+}
+
+/** Public view of a managed node — surfaced to `/api/nodes` callers. */
+export interface ManagedNodeInfo {
+  /** Friendly container id passed at create time. */
+  id: string;
+  /** Opaque dockerId (`pid:token`) — pass to stop/getStats/getLogs. */
+  dockerId: string;
+  partyId: string;
+  profile: 'storage' | 'transaction';
+  /** Runtime state derived from `Handle.alive`. */
+  status: 'running' | 'stopped';
+  spawnedAt: string;
+  workdir: string;
+  ports: { health: number; metrics: number; p2p: number };
+}
+
+/**
+ * Listener invoked when a managed node's lifecycle state changes
+ * (create, child exit, manual stop). Subscribe via
+ * `HostProcessOrchestrator.onStateChange`.
+ */
+export type NodeStateListener = (info: ManagedNodeInfo) => void;
+
+const TOKEN_SEPARATOR = ':';
+
+/**
+ * Encode an opaque handle that callers treat the same way they treat a
+ * Docker container hash. The shape is `<pid>:<token>`; tokens are hex
+ * generated from `crypto.randomBytes` so they never contain `:`.
+ */
+export function encodeDockerId(pid: number, token: string): string {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error(`Invalid pid for docker id: ${pid}`);
+  }
+  if (token.length === 0 || token.includes(TOKEN_SEPARATOR)) {
+    throw new Error(`Invalid token for docker id: ${JSON.stringify(token)}`);
+  }
+  return `${pid}${TOKEN_SEPARATOR}${token}`;
+}
+
+export function decodeDockerId(id: string): { pid: number; token: string } {
+  const idx = id.indexOf(TOKEN_SEPARATOR);
+  if (idx <= 0) {
+    throw new Error(`Malformed dockerId: ${id}`);
+  }
+  const pid = Number.parseInt(id.slice(0, idx), 10);
+  const token = id.slice(idx + 1);
+  if (!Number.isInteger(pid) || pid <= 0 || token.length === 0) {
+    throw new Error(`Malformed dockerId: ${id}`);
+  }
+  return { pid, token };
+}

package/src/server/__tests__/bus.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+
+import { EventBus } from '../events/bus.js';
+import type { LocalUiEvent } from '../events/types.js';
+
+describe('EventBus', () => {
+  it('delivers events to subscribers in order', () => {
+    const bus = new EventBus();
+    const received: LocalUiEvent[] = [];
+    bus.subscribe((e) => received.push(e));
+    bus.publish({ type: 'trust-circle-changed', kind: 'invited' });
+    bus.publish({ type: 'trust-circle-changed', kind: 'revoked' });
+    expect(received).toEqual([
+      { type: 'trust-circle-changed', kind: 'invited' },
+      { type: 'trust-circle-changed', kind: 'revoked' },
+    ]);
+  });
+
+  it('unsubscribe stops further deliveries', () => {
+    const bus = new EventBus();
+    const received: LocalUiEvent[] = [];
+    const unsub = bus.subscribe((e) => received.push(e));
+    bus.publish({ type: 'trust-circle-changed', kind: 'invited' });
+    unsub();
+    bus.publish({ type: 'trust-circle-changed', kind: 'redeemed' });
+    expect(received).toHaveLength(1);
+    expect(bus.listenerCount()).toBe(0);
+  });
+
+  it('one listener throwing does not block others', () => {
+    const bus = new EventBus();
+    const received: LocalUiEvent[] = [];
+    bus.subscribe(() => { throw new Error('bad listener'); });
+    bus.subscribe((e) => received.push(e));
+    bus.publish({ type: 'trust-circle-changed', kind: 'invited' });
+    expect(received).toHaveLength(1);
+  });
+});

package/src/server/__tests__/error-handler.test.ts

@@ -0,0 +1,96 @@
+import Fastify from 'fastify';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { TrustCircleError } from '../../auth/types.js';
+import { NatError } from '../../nat/types.js';
+import { UpdateErrorException } from '../../update/types.js';
+import { registerErrorHandler } from '../error-handler.js';
+
+describe('error handler', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    app = Fastify();
+    registerErrorHandler(app);
+    app.get('/trust/:code', async (req) => {
+      const { code } = req.params as { code: string };
+      throw new TrustCircleError(code as never, `trust err: ${code}`);
+    });
+    app.get('/nat/:code', async (req) => {
+      const { code } = req.params as { code: string };
+      throw new NatError(code as never, `nat err: ${code}`);
+    });
+    app.get('/update/:code', async (req) => {
+      const { code } = req.params as { code: string };
+      throw new UpdateErrorException(code as never, `update err: ${code}`);
+    });
+    app.get('/unknown', async () => {
+      throw new Error('mystery');
+    });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('TrustCircleError invalid_label → 400', async () => {
+    const res = await app.inject({ method: 'GET', url: '/trust/invalid_label' });
+    expect(res.statusCode).toBe(400);
+    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
+    expect(body).toEqual({
+      ok: false,
+      error: { code: 'invalid_label', message: 'trust err: invalid_label' },
+    });
+  });
+
+  it('TrustCircleError not_found → 404', async () => {
+    const res = await app.inject({ method: 'GET', url: '/trust/not_found' });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('TrustCircleError already_redeemed → 404', async () => {
+    const res = await app.inject({ method: 'GET', url: '/trust/already_redeemed' });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('TrustCircleError expired → 410', async () => {
+    const res = await app.inject({ method: 'GET', url: '/trust/expired' });
+    expect(res.statusCode).toBe(410);
+  });
+
+  it('TrustCircleError storage_error → 500', async () => {
+    const res = await app.inject({ method: 'GET', url: '/trust/storage_error' });
+    expect(res.statusCode).toBe(500);
+  });
+
+  it('NatError invalid_config → 400', async () => {
+    const res = await app.inject({ method: 'GET', url: '/nat/invalid_config' });
+    expect(res.statusCode).toBe(400);
+    const body = res.json() as { error: { code: string } };
+    expect(body.error.code).toBe('invalid_config');
+  });
+
+  it('NatError secrets_unavailable → 500', async () => {
+    const res = await app.inject({ method: 'GET', url: '/nat/secrets_unavailable' });
+    expect(res.statusCode).toBe(500);
+  });
+
+  it('UpdateErrorException apply_in_progress → 409', async () => {
+    const res = await app.inject({ method: 'GET', url: '/update/apply_in_progress' });
+    expect(res.statusCode).toBe(409);
+  });
+
+  it('UpdateErrorException no_update_available → 400', async () => {
+    const res = await app.inject({ method: 'GET', url: '/update/no_update_available' });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('unknown Error → 500 internal', async () => {
+    const res = await app.inject({ method: 'GET', url: '/unknown' });
+    expect(res.statusCode).toBe(500);
+    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe('internal');
+    expect(body.error.message).toBe('mystery');
+  });
+});

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

@@ -0,0 +1,179 @@
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import Fastify from 'fastify';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { EventBus } from '../events/bus.js';
+import { registerErrorHandler } from '../error-handler.js';
+import { registerNodesRoutes, tailLogFile } from '../routes/nodes.js';
+import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
+import type { ManagedNodeInfo, NodeStateListener } from '../../orchestrator/types.js';
+
+interface FakeOrchestrator extends HostProcessOrchestrator {
+  __nodes: Map<string, ManagedNodeInfo>;
+  __listeners: Set<NodeStateListener>;
+  __stoppedDockerIds: string[];
+}
+
+function fakeOrchestrator(initial: ManagedNodeInfo[] = []): FakeOrchestrator {
+  const nodes = new Map(initial.map((n) => [n.dockerId, n]));
+  const listeners = new Set<NodeStateListener>();
+  const stopped: string[] = [];
+  const inst = {
+    listNodes: () => [...nodes.values()],
+    getNode: (id: string) => {
+      const direct = nodes.get(id);
+      if (direct) return direct;
+      for (const n of nodes.values()) if (n.id === id) return n;
+      return undefined;
+    },
+    resolveDockerId: (id: string) => {
+      if (nodes.has(id)) return id;
+      for (const n of nodes.values()) if (n.id === id) return n.dockerId;
+      return undefined;
+    },
+    onStateChange: (l: NodeStateListener) => { listeners.add(l); return () => { listeners.delete(l); }; },
+    stopContainer: async (dockerId: string) => {
+      stopped.push(dockerId);
+      const node = nodes.get(dockerId);
+      if (node) {
+        const next: ManagedNodeInfo = { ...node, status: 'stopped' };
+        nodes.set(dockerId, next);
+        for (const l of listeners) l(next);
+      }
+    },
+    getStats: async () => ({ cpuPercent: 1, memoryBytes: 2, networkRxBytes: 3, networkTxBytes: 4 }),
+    __nodes: nodes,
+    __listeners: listeners,
+    __stoppedDockerIds: stopped,
+  } as unknown as FakeOrchestrator;
+  return inst;
+}
+
+const SAMPLE_NODE: ManagedNodeInfo = {
+  id: 'alice',
+  dockerId: '12345:abcdef',
+  partyId: 'party-alice',
+  profile: 'storage',
+  status: 'running',
+  spawnedAt: '2025-01-01T00:00:00Z',
+  workdir: '',
+  ports: { health: 11, metrics: 12, p2p: 13 },
+};
+
+describe('/api/nodes routes', () => {
+  let app: ReturnType<typeof Fastify>;
+  let bus: EventBus;
+  let orchestrator: FakeOrchestrator;
+  let workdir: string;
+
+  beforeEach(async () => {
+    workdir = mkdtempSync(join(tmpdir(), 'cadre-host-nodes-'));
+    bus = new EventBus();
+    app = Fastify();
+    registerErrorHandler(app);
+    orchestrator = fakeOrchestrator([{ ...SAMPLE_NODE, workdir }]);
+    registerNodesRoutes(app, { orchestrator });
+    // Mirror what createLocalUiServer.start() does — forward orchestrator
+    // state changes onto the bus. The route itself doesn't publish; the
+    // listener is the single publication point.
+    orchestrator.onStateChange((info) => {
+      bus.publish({
+        type: 'node-state-changed',
+        nodeId: info.id,
+        status: info.status === 'running' ? 'running' : 'stopped',
+      });
+    });
+  });
+
+  afterEach(async () => {
+    await app.close();
+    rmSync(workdir, { recursive: true, force: true });
+  });
+
+  it('GET /api/nodes lists known nodes', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/nodes' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { ok: boolean; data: { nodes: Array<{ id: string }> } };
+    expect(body.ok).toBe(true);
+    expect(body.data.nodes).toHaveLength(1);
+    expect(body.data.nodes[0]?.id).toBe('alice');
+  });
+
+  it('GET /api/nodes/:id returns details with stats', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/nodes/alice' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { data: { node: { id: string }; stats: { cpuPercent: number } } };
+    expect(body.data.node.id).toBe('alice');
+    expect(body.data.stats.cpuPercent).toBe(1);
+  });
+
+  it('GET /api/nodes/:id 404 for unknown', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/nodes/nobody' });
+    expect(res.statusCode).toBe(404);
+    const body = res.json() as { ok: boolean; error: { code: string } };
+    expect(body.error.code).toBe('not_found');
+  });
+
+  it('GET /api/nodes/:id/logs returns tail of node.log', async () => {
+    // Mirror the orchestrator's defaultLogPath layout: <workdir>/node.log
+    writeFileSync(join(workdir, 'node.log'), 'one\ntwo\nthree\nfour\nfive\n', 'utf8');
+    const res = await app.inject({ method: 'GET', url: '/api/nodes/alice/logs?lines=2' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { data: { lines: string[] } };
+    expect(body.data.lines).toEqual(['four', 'five']);
+  });
+
+  it('GET /api/nodes/:id/logs returns [] when log file missing', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/nodes/alice/logs' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { data: { lines: string[] } };
+    expect(body.data.lines).toEqual([]);
+  });
+
+  it('POST /api/nodes/:id/stop calls orchestrator and publishes exactly one event via the listener', async () => {
+    const events: unknown[] = [];
+    bus.subscribe((e) => events.push(e));
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/alice/stop' });
+    expect(res.statusCode).toBe(200);
+    expect(orchestrator.__stoppedDockerIds).toContain(SAMPLE_NODE.dockerId);
+    // Exactly one event — the orchestrator listener publishes; the route
+    // does not re-publish (regression guard).
+    expect(events).toEqual([
+      { type: 'node-state-changed', nodeId: 'alice', status: 'stopped' },
+    ]);
+  });
+
+  it('POST /api/nodes/:id/start returns 501 not_implemented', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/alice/start' });
+    expect(res.statusCode).toBe(501);
+    const body = res.json() as { error: { code: string } };
+    expect(body.error.code).toBe('not_implemented');
+  });
+
+  it('POST /api/nodes/:id/restart returns 501 not_implemented', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/alice/restart' });
+    expect(res.statusCode).toBe(501);
+  });
+});
+
+describe('tailLogFile', () => {
+  it('returns [] for missing file', () => {
+    expect(tailLogFile(join(tmpdir(), 'definitely-not-here-' + Date.now()), 10)).toEqual([]);
+  });
+
+  it('returns the last N lines from a multi-line file', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'cadre-host-tail-'));
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'sample.log');
+    writeFileSync(path, Array.from({ length: 50 }, (_, i) => `line-${i + 1}`).join('\n') + '\n', 'utf8');
+    try {
+      const last3 = tailLogFile(path, 3);
+      expect(last3).toEqual(['line-48', 'line-49', 'line-50']);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/server/__tests__/origin-guard.test.ts

@@ -0,0 +1,72 @@
+import Fastify from 'fastify';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { registerOriginGuard } from '../origin-guard.js';
+
+describe('origin guard', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    app = Fastify();
+    registerOriginGuard(app, { port: 8765 });
+    app.get('/ping', async () => ({ ok: true, data: { pong: true } }));
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('accepts 127.0.0.1:<port>', async () => {
+    const res = await app.inject({ method: 'GET', url: '/ping', headers: { host: '127.0.0.1:8765' } });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('accepts localhost:<port>', async () => {
+    const res = await app.inject({ method: 'GET', url: '/ping', headers: { host: 'localhost:8765' } });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('accepts case-insensitive localhost', async () => {
+    const res = await app.inject({ method: 'GET', url: '/ping', headers: { host: 'LOCALHOST:8765' } });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('rejects mismatched host', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/ping',
+      headers: { host: 'evil.example.com' },
+    });
+    expect(res.statusCode).toBe(403);
+    const body = res.json() as { ok: boolean; error: { code: string } };
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe('forbidden_origin');
+  });
+
+  it('rejects host with wrong port', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/ping',
+      headers: { host: '127.0.0.1:9999' },
+    });
+    expect(res.statusCode).toBe(403);
+  });
+
+  it('accepts request with matching Origin', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/ping',
+      headers: { host: '127.0.0.1:8765', origin: 'http://127.0.0.1:8765' },
+    });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('rejects request with mismatched Origin', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/ping',
+      headers: { host: '127.0.0.1:8765', origin: 'http://evil.example.com' },
+    });
+    expect(res.statusCode).toBe(403);
+  });
+});