@serfab/cadre-host 0.7.1 → 0.9.0

package/src/push/index.ts

@@ -0,0 +1,146 @@
+/**
+ * Push (FCM/APNs) credential storage + resolution for cadre-host.
+ *
+ * The platform-push secrets a self-hosted deployment provisions live in the host
+ * secret store (keytar with file-store fallback — the same store DDNS tokens use);
+ * the non-secret app-config bits (APNs bundle id / sandbox toggle, cooldown /
+ * debounce) live in `host.config.json` (`PushSettings`). At node-spawn time the
+ * orchestrator's `pushResolver` calls {@link resolvePushCredentials}, which reads
+ * BOTH and merges them into the `PushCredentials` block written into the spawned
+ * node's `cadre.json`.
+ *
+ * Secret hygiene: the FCM service-account fields and the APNs `.p8` key are stored
+ * ONLY in the secret store, never in `host.config.json` and never in `state.json`.
+ * They are re-read on every spawn so a restart picks up rotated keys, and the
+ * resolver redacts on any log line. A partial credential set (a present platform
+ * missing required fields) is rejected — fail fast, not at first push.
+ */
+
+import debug from 'debug';
+
+import type { PushCredentials, FcmCredentials, ApnsCredentials } from '@serfab/cadre-core';
+import { validatePushCredentials } from '@serfab/cadre-core';
+
+import type { SecretsStore } from '../nat/secrets/index.js';
+import type { PushSettings } from '../installer/config.js';
+
+const log = debug('cadre:host:push');
+
+/** Push platform whose secret bundle lives in the secret store. */
+export type PushSecretPlatform = 'fcm' | 'apns';
+
+/** Build the secret-store account key for a platform's credential bundle. */
+export function pushAccount(platform: PushSecretPlatform): string {
+  return `push:${platform}`;
+}
+
+/** FCM secret bundle persisted in the secret store (the whole set is sensitive). */
+export interface FcmSecret {
+  projectId: string;
+  clientEmail: string;
+  /** Service-account RSA private key, PEM. */
+  privateKey: string;
+}
+
+/**
+ * APNs secret bundle persisted in the secret store. `bundleId` / `production` are
+ * NOT here — they are non-secret app-config in {@link PushSettings}.
+ */
+export interface ApnsSecret {
+  keyId: string;
+  teamId: string;
+  /** `.p8` ES256 private key, PEM. */
+  privateKey: string;
+}
+
+/** Store (or replace) the FCM service-account secret bundle. */
+export async function setFcmSecret(secrets: SecretsStore, secret: FcmSecret): Promise<void> {
+  await secrets.set(pushAccount('fcm'), JSON.stringify(secret));
+}
+
+/** Store (or replace) the APNs auth-key secret bundle. */
+export async function setApnsSecret(secrets: SecretsStore, secret: ApnsSecret): Promise<void> {
+  await secrets.set(pushAccount('apns'), JSON.stringify(secret));
+}
+
+/** Remove a platform's secret bundle. Returns true if one was present. */
+export async function clearPushSecret(secrets: SecretsStore, platform: PushSecretPlatform): Promise<boolean> {
+  return secrets.delete(pushAccount(platform));
+}
+
+/** Read a platform's stored secret bundle, or null when unset. */
+async function readSecret<T>(secrets: SecretsStore, platform: PushSecretPlatform): Promise<T | null> {
+  const raw = await secrets.get(pushAccount(platform));
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    throw new Error(`Stored ${platform} push secret is not valid JSON: ${(err as Error).message}`, { cause: err });
+  }
+}
+
+/**
+ * Resolve the full {@link PushCredentials} block to inject into a spawned node,
+ * merging the secret-store bundles with the non-secret {@link PushSettings}.
+ *
+ * Returns `undefined` when NO platform is configured (push is opt-in — the node
+ * then constructs no fan-out). Throws when a configured platform is incomplete
+ * (e.g. APNs secret present but `bundleId` unset), so a misconfig surfaces at the
+ * spawn boundary rather than silently at first push.
+ */
+export async function resolvePushCredentials(
+  secrets: SecretsStore,
+  settings: PushSettings | undefined,
+): Promise<PushCredentials | undefined> {
+  const fcmSecret = await readSecret<FcmSecret>(secrets, 'fcm');
+  const apnsSecret = await readSecret<ApnsSecret>(secrets, 'apns');
+
+  if (!fcmSecret && !apnsSecret) return undefined;
+
+  const push: PushCredentials = {};
+  if (fcmSecret) {
+    const fcm: FcmCredentials = {
+      projectId: fcmSecret.projectId,
+      clientEmail: fcmSecret.clientEmail,
+      privateKey: fcmSecret.privateKey,
+    };
+    push.fcm = fcm;
+  }
+  if (apnsSecret) {
+    const apns: ApnsCredentials = {
+      keyId: apnsSecret.keyId,
+      teamId: apnsSecret.teamId,
+      bundleId: settings?.apns?.bundleId ?? '',
+      privateKey: apnsSecret.privateKey,
+      ...(settings?.apns?.production !== undefined ? { production: settings.apns.production } : {}),
+    };
+    push.apns = apns;
+  }
+  if (settings?.cooldownMs !== undefined) push.cooldownMs = settings.cooldownMs;
+  if (settings?.debounceMs !== undefined) push.debounceMs = settings.debounceMs;
+
+  const errors = validatePushCredentials(push);
+  if (errors.length > 0) {
+    throw new Error(`Invalid push credentials: ${errors.join('; ')}`);
+  }
+  log('resolved push credentials (fcm=%s apns=%s)', !!push.fcm, !!push.apns);
+  return push;
+}
+
+/**
+ * A description of which push platforms are configured, for the `push status` CLI
+ * and any UI — derived without exposing any secret material.
+ */
+export interface PushStatus {
+  fcm: boolean;
+  apns: boolean;
+}
+
+/** Report which platforms have a stored secret bundle (no secret material). */
+export async function pushStatus(secrets: SecretsStore): Promise<PushStatus> {
+  const accounts = await secrets.list();
+  return {
+    fcm: accounts.includes(pushAccount('fcm')),
+    apns: accounts.includes(pushAccount('apns')),
+  };
+}

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

@@ -1,9 +1,10 @@
-import Fastify from 'fastify';
+import Fastify, { type FastifyRequest } 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 { GrantError } from '../../donation/types.js';
 import { registerErrorHandler } from '../error-handler.js';
 
 describe('error handler', () => {
@@ -12,18 +13,22 @@ describe('error handler', () => {
   beforeEach(async () => {
     app = Fastify();
     registerErrorHandler(app);
-    app.get('/trust/:code', async (req) => {
+    app.get('/trust/:code', async (req: FastifyRequest) => {
       const { code } = req.params as { code: string };
       throw new TrustCircleError(code as never, `trust err: ${code}`);
     });
-    app.get('/nat/:code', async (req) => {
+    app.get('/nat/:code', async (req: FastifyRequest) => {
       const { code } = req.params as { code: string };
       throw new NatError(code as never, `nat err: ${code}`);
     });
-    app.get('/update/:code', async (req) => {
+    app.get('/update/:code', async (req: FastifyRequest) => {
       const { code } = req.params as { code: string };
       throw new UpdateErrorException(code as never, `update err: ${code}`);
     });
+    app.get('/grant/:code', async (req: FastifyRequest) => {
+      const { code } = req.params as { code: string };
+      throw new GrantError(code as never, `grant err: ${code}`);
+    });
     app.get('/unknown', async () => {
       throw new Error('mystery');
     });
@@ -85,6 +90,23 @@ describe('error handler', () => {
     expect(res.statusCode).toBe(400);
   });
 
+  it('GrantError invalid_max_nodes → 400', async () => {
+    const res = await app.inject({ method: 'GET', url: '/grant/invalid_max_nodes' });
+    expect(res.statusCode).toBe(400);
+    const body = res.json() as { error: { code: string } };
+    expect(body.error.code).toBe('invalid_max_nodes');
+  });
+
+  it('GrantError not_found → 404', async () => {
+    const res = await app.inject({ method: 'GET', url: '/grant/not_found' });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('GrantError storage_error → 500', async () => {
+    const res = await app.inject({ method: 'GET', url: '/grant/storage_error' });
+    expect(res.statusCode).toBe(500);
+  });
+
   it('unknown Error → 500 internal', async () => {
     const res = await app.inject({ method: 'GET', url: '/unknown' });
     expect(res.statusCode).toBe(500);

package/src/server/__tests__/grants-admin-route.test.ts

@@ -0,0 +1,73 @@
+import Fastify from 'fastify';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { registerErrorHandler } from '../error-handler.js';
+import { registerGrantsAdminRoutes } from '../routes/grants-admin.js';
+import { GrantService, GrantStore, createGrantAdminHandlers } from '../../donation/index.js';
+import type { Grant } from '../../donation/index.js';
+
+let tmpRoot: string;
+let app: ReturnType<typeof Fastify>;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grants-route-'));
+  const service = new GrantService({ store: new GrantStore(tmpRoot) });
+  app = Fastify();
+  registerErrorHandler(app);
+  registerGrantsAdminRoutes(app, { handlers: createGrantAdminHandlers(service) });
+});
+
+afterEach(async () => {
+  await app.close();
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('/grants-admin routes', () => {
+  it('POST issues a grant, GET lists it, DELETE revokes it', async () => {
+    const post = await app.inject({
+      method: 'POST',
+      url: '/grants-admin',
+      payload: { label: "Alice's cadre", maxNodes: 2 },
+    });
+    expect(post.statusCode).toBe(200);
+    const created = (post.json() as { grant: Grant }).grant;
+    expect(created.token).toBeTruthy();
+    expect(created.maxNodes).toBe(2);
+
+    const list = await app.inject({ method: 'GET', url: '/grants-admin' });
+    expect(list.statusCode).toBe(200);
+    expect((list.json() as { grants: Grant[] }).grants.map(g => g.token)).toContain(created.token);
+
+    const del = await app.inject({
+      method: 'DELETE',
+      url: `/grants-admin/${encodeURIComponent(created.token)}`,
+    });
+    expect(del.statusCode).toBe(200);
+
+    // Revoked → still listed, now carries revokedAt.
+    const after = await app.inject({ method: 'GET', url: '/grants-admin' });
+    const row = (after.json() as { grants: Grant[] }).grants.find(g => g.token === created.token);
+    expect(row?.revokedAt).toBeTruthy();
+  });
+
+  it('POST with an empty label → 400 invalid_label', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants-admin', payload: { label: '  ' } });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_label');
+  });
+
+  it('POST with a bad maxNodes → 400 invalid_max_nodes', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants-admin', payload: { label: 'X', maxNodes: 0 } });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_max_nodes');
+  });
+
+  it('DELETE of an unknown token → 404 not_found', async () => {
+    const res = await app.inject({ method: 'DELETE', url: '/grants-admin/nope' });
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('not_found');
+  });
+});

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

@@ -0,0 +1,189 @@
+/**
+ * Grantee-facing `/grants` route tests — the bearer-gated provisioning surface.
+ *
+ * Uses a fake orchestrator (no real children) so the focus is the HTTP contract:
+ * bearer auth, request validation, per-grant ownership isolation, the quota gate,
+ * and seedToken redaction. The live-node round-trips (peer/seed) are covered by
+ * the cross-package integration scenario.
+ */
+
+import Fastify from 'fastify';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type {
+  Orchestrator,
+  OrchestratorCreateRequest,
+  OrchestratorCreateResult,
+  OrchestratorStats,
+} from '@serfab/cadre-provider';
+
+import { registerErrorHandler } from '../error-handler.js';
+import { registerGrantsRoutes } from '../routes/grants.js';
+import { DonationService } from '../../donation/donation-service.js';
+import { DonationStore } from '../../donation/donation-store.js';
+import { GrantService } from '../../donation/grant-service.js';
+import { GrantStore } from '../../donation/grant-store.js';
+
+class FakeOrchestrator implements Orchestrator {
+  stopped: string[] = [];
+  removed: string[] = [];
+  private counter = 0;
+  async createContainer(_request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
+    const n = ++this.counter;
+    return {
+      dockerId: `dock_${n}`,
+      healthEndpoint: `http://127.0.0.1:${9000 + n}/health`,
+      metricsEndpoint: `http://127.0.0.1:${9000 + n}/metrics`,
+      seedEndpoint: `http://127.0.0.1:${9000 + n}/seed`,
+      seedToken: `seed-token-${n}`,
+      p2pPort: 4000 + n,
+    };
+  }
+  async stopContainer(id: string): Promise<void> { this.stopped.push(id); }
+  async removeContainer(id: string): Promise<void> { this.removed.push(id); }
+  async getStats(): Promise<OrchestratorStats> {
+    return { cpuPercent: 0, memoryBytes: 0, networkRxBytes: 0, networkTxBytes: 0 };
+  }
+  async isRunning(): Promise<boolean> { return true; }
+  async getLogs(): Promise<string> { return ''; }
+}
+
+let tmpRoot: string;
+let app: ReturnType<typeof Fastify>;
+let grants: GrantService;
+let token: string;
+
+const body = {
+  partyId: 'party-P',
+  bootstrapNodes: ['/ip4/127.0.0.1/tcp/4001/p2p/12D3KooReq'],
+  ownerKeys: ['owner-key-b64url'],
+};
+
+const bearer = (t: string) => ({ authorization: `Bearer ${t}` });
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grants-svc-route-'));
+  grants = new GrantService({ store: new GrantStore(join(tmpRoot, 'grants')) });
+  token = grants.issue({ label: 'Alice', maxNodes: 2 }).token;
+  const donations = new DonationService({
+    orchestrator: new FakeOrchestrator(),
+    grants,
+    store: new DonationStore(join(tmpRoot, 'donations')),
+  });
+  app = Fastify();
+  registerErrorHandler(app);
+  registerGrantsRoutes(app, { donations, grants });
+});
+
+afterEach(async () => {
+  await app.close();
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('POST /grants', () => {
+  it('provisions a donated node → 201, awaiting_seed, seedToken redacted', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    expect(res.statusCode).toBe(201);
+    const donation = (res.json() as { data: { donation: Record<string, unknown> } }).data.donation;
+    expect(donation.status).toBe('awaiting_seed');
+    expect(donation.partyId).toBe('party-P');
+    expect(donation.seedToken).toBeUndefined();
+    expect(donation.seedEndpoint).toBeUndefined();
+  });
+
+  it('rejects a missing bearer → 401', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', payload: body });
+    expect(res.statusCode).toBe(401);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('unauthorized');
+  });
+
+  it('rejects an unknown bearer → 401', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', headers: bearer('nope'), payload: body });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a missing partyId → 400 invalid_request', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants', headers: bearer(token),
+      payload: { bootstrapNodes: body.bootstrapNodes, ownerKeys: body.ownerKeys },
+    });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_request');
+  });
+
+  it('rejects empty ownerKeys → 400 invalid_request', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants', headers: bearer(token),
+      payload: { ...body, ownerKeys: [] },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('enforces the grant quota → 429 quota_exceeded once maxNodes is reached', async () => {
+    const g = grants.issue({ label: 'Bob', maxNodes: 1 }).token;
+    const first = await app.inject({ method: 'POST', url: '/grants', headers: bearer(g), payload: body });
+    expect(first.statusCode).toBe(201);
+    const second = await app.inject({ method: 'POST', url: '/grants', headers: bearer(g), payload: body });
+    expect(second.statusCode).toBe(429);
+    expect((second.json() as { error: { code: string } }).error.code).toBe('quota_exceeded');
+  });
+});
+
+describe('GET /grants auth', () => {
+  it('rejects an unknown bearer → 401 unauthorized (code matches the status)', async () => {
+    const res = await app.inject({ method: 'GET', url: '/grants', headers: bearer('nope') });
+    expect(res.statusCode).toBe(401);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('unauthorized');
+  });
+});
+
+describe('GET /grants (ownership isolation)', () => {
+  it('lists only the donations the presented grant authorized', async () => {
+    const other = grants.issue({ label: 'Carol' }).token;
+    await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    await app.inject({ method: 'POST', url: '/grants', headers: bearer(other), payload: body });
+
+    const mine = await app.inject({ method: 'GET', url: '/grants', headers: bearer(token) });
+    const donations = (mine.json() as { data: { donations: Array<{ grantToken: string }> } }).data.donations;
+    expect(donations).toHaveLength(1);
+    expect(donations[0].grantToken).toBe(token);
+  });
+
+  it('a foreign grant cannot read another grant’s donation → 404', async () => {
+    const other = grants.issue({ label: 'Carol' }).token;
+    const created = await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    const id = (created.json() as { data: { donation: { id: string } } }).data.donation.id;
+
+    const mine = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(token) });
+    expect(mine.statusCode).toBe(200);
+
+    const foreign = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(other) });
+    expect(foreign.statusCode).toBe(404);
+  });
+});
+
+describe('PUT /grants/:id/seed validation', () => {
+  it('rejects a missing seed body → 400 invalid_request', async () => {
+    const created = await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    const id = (created.json() as { data: { donation: { id: string } } }).data.donation.id;
+    const res = await app.inject({ method: 'PUT', url: `/grants/${id}/seed`, headers: bearer(token), payload: {} });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_request');
+  });
+});
+
+describe('DELETE /grants/:id', () => {
+  it('terminates a donation and drops it from the live tally', async () => {
+    const created = await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    const id = (created.json() as { data: { donation: { id: string } } }).data.donation.id;
+
+    const del = await app.inject({ method: 'DELETE', url: `/grants/${id}`, headers: bearer(token) });
+    expect(del.statusCode).toBe(200);
+
+    const one = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(token) });
+    expect((one.json() as { data: { donation: { status: string } } }).data.donation.status).toBe('terminated');
+  });
+});

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

@@ -15,25 +15,48 @@ interface FakeOrchestrator extends HostProcessOrchestrator {
   __nodes: Map<string, ManagedNodeInfo>;
   __listeners: Set<NodeStateListener>;
   __stoppedDockerIds: string[];
+  __ensured: number;
+  __restarted: number;
 }
 
-function fakeOrchestrator(initial: ManagedNodeInfo[] = []): FakeOrchestrator {
+function fakeOrchestrator(
+  initial: ManagedNodeInfo[] = [],
+  opts: { ownerId?: string; hasOwnerConfig?: boolean } = {},
+): FakeOrchestrator {
   const nodes = new Map(initial.map((n) => [n.dockerId, n]));
   const listeners = new Set<NodeStateListener>();
   const stopped: string[] = [];
+  const counters = { ensured: 0, restarted: 0 };
+  const findById = (id: string): ManagedNodeInfo | undefined => {
+    const direct = nodes.get(id);
+    if (direct) return direct;
+    for (const n of nodes.values()) if (n.id === id) return n;
+    return undefined;
+  };
   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;
-    },
+    getNode: (id: string) => findById(id),
     resolveDockerId: (id: string) => {
       if (nodes.has(id)) return id;
       for (const n of nodes.values()) if (n.id === id) return n.dockerId;
       return undefined;
     },
+    isOwnerNode: (id: string) => {
+      if (!opts.ownerId) return false;
+      const node = findById(id);
+      return id === opts.ownerId || node?.id === opts.ownerId;
+    },
+    hasOwnerConfig: () => opts.hasOwnerConfig ?? false,
+    ensureOwnerNode: async () => {
+      counters.ensured++;
+      const node = opts.ownerId ? findById(opts.ownerId) : undefined;
+      return node ?? { id: opts.ownerId, status: 'running' } as unknown as ManagedNodeInfo;
+    },
+    restartOwnerNode: async () => {
+      counters.restarted++;
+      const node = opts.ownerId ? findById(opts.ownerId) : undefined;
+      return node ?? { id: opts.ownerId, status: 'running' } as unknown as ManagedNodeInfo;
+    },
     onStateChange: (l: NodeStateListener) => { listeners.add(l); return () => { listeners.delete(l); }; },
     stopContainer: async (dockerId: string) => {
       stopped.push(dockerId);
@@ -48,6 +71,8 @@ function fakeOrchestrator(initial: ManagedNodeInfo[] = []): FakeOrchestrator {
     __nodes: nodes,
     __listeners: listeners,
     __stoppedDockerIds: stopped,
+    get __ensured() { return counters.ensured; },
+    get __restarted() { return counters.restarted; },
   } as unknown as FakeOrchestrator;
   return inst;
 }
@@ -60,7 +85,7 @@ const SAMPLE_NODE: ManagedNodeInfo = {
   status: 'running',
   spawnedAt: '2025-01-01T00:00:00Z',
   workdir: '',
-  ports: { health: 11, metrics: 12, p2p: 13 },
+  ports: { health: 11, metrics: 12, p2p: 13, admin: 14 },
 };
 
 describe('/api/nodes routes', () => {
@@ -146,17 +171,72 @@ describe('/api/nodes routes', () => {
     ]);
   });
 
-  it('POST /api/nodes/:id/start returns 501 not_implemented', async () => {
+  it('POST /api/nodes/:id/start on a non-owner node 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 () => {
+  it('POST /api/nodes/:id/restart on a non-owner node returns 501 not_implemented', async () => {
     const res = await app.inject({ method: 'POST', url: '/api/nodes/alice/restart' });
     expect(res.statusCode).toBe(501);
   });
+
+  it('POST /api/nodes/:id/start on an unknown node returns 404', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/nobody/start' });
+    expect(res.statusCode).toBe(404);
+    const body = res.json() as { error: { code: string } };
+    expect(body.error.code).toBe('not_found');
+  });
+});
+
+describe('/api/nodes — owner node start/restart', () => {
+  const OWNER_NODE: ManagedNodeInfo = {
+    id: 'owner',
+    dockerId: '999:tok',
+    partyId: 'install-id',
+    profile: 'storage',
+    status: 'running',
+    spawnedAt: '2025-01-01T00:00:00Z',
+    workdir: '',
+    ports: { health: 1, metrics: 2, p2p: 4555, admin: 3 },
+    owner: true,
+  };
+
+  let app: ReturnType<typeof Fastify>;
+  let orchestrator: FakeOrchestrator;
+
+  beforeEach(() => {
+    app = Fastify();
+    registerErrorHandler(app);
+    orchestrator = fakeOrchestrator([OWNER_NODE], { ownerId: 'owner', hasOwnerConfig: true });
+    registerNodesRoutes(app, { orchestrator });
+  });
+
+  afterEach(async () => { await app.close(); });
+
+  it('start ensures the owner node', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/owner/start' });
+    expect(res.statusCode).toBe(200);
+    expect(orchestrator.__ensured).toBe(1);
+  });
+
+  it('restart re-spawns the owner node', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/owner/restart' });
+    expect(res.statusCode).toBe(200);
+    expect(orchestrator.__restarted).toBe(1);
+  });
+
+  it('start returns 501 when there is no saved owner config', async () => {
+    const app2 = Fastify();
+    registerErrorHandler(app2);
+    const orch2 = fakeOrchestrator([OWNER_NODE], { ownerId: 'owner', hasOwnerConfig: false });
+    registerNodesRoutes(app2, { orchestrator: orch2 });
+    const res = await app2.inject({ method: 'POST', url: '/api/nodes/owner/start' });
+    expect(res.statusCode).toBe(501);
+    await app2.close();
+  });
 });
 
 describe('tailLogFile', () => {

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

@@ -131,7 +131,7 @@ describe('publisher wiring', () => {
       status: 'stopped',
       spawnedAt: 'x',
       workdir: '/tmp',
-      ports: { health: 1, metrics: 2, p2p: 3 },
+      ports: { health: 1, metrics: 2, p2p: 3, admin: 4 },
     });
     expect(received).toContainEqual({
       type: 'node-state-changed',