@serfab/cadre-host 0.8.1 → 0.9.0

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

@@ -9,6 +9,7 @@ import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
 import type { TrustCircleService } from '../../auth/index.js';
 import type { NatService } from '../../nat/index.js';
 import type { NatStatusSnapshot } from '../../nat/types.js';
+import { GrantService, GrantStore } from '../../donation/index.js';
 
 function fakeOrchestrator(): HostProcessOrchestrator {
   return {
@@ -176,3 +177,77 @@ describe('createLocalUiServer smoke', () => {
     expect(body.error.code).toBe('not_found');
   });
 });
+
+// Donor-only mode: the common case (ownCadre.enabled=false). No owner node, so
+// no trustCircle / NAT are wired. The donor surface (/grants-admin) is up, and
+// the founder-only surfaces (/auth, /nat) 404 to keep the surface honest.
+describe('createLocalUiServer smoke — donor-only (no owner node)', () => {
+  let dataDir: string;
+  let server: ReturnType<typeof createLocalUiServer>;
+  let baseUrl: string;
+
+  beforeEach(async () => {
+    dataDir = mkdtempSync(join(tmpdir(), 'cadre-host-donor-'));
+    writeConfig(dataDir);
+    server = createLocalUiServer({
+      uiPort: 8765,
+      dataDir,
+      orchestrator: fakeOrchestrator(),
+      grants: new GrantService({ store: new GrantStore(dataDir) }),
+      forcePort: 0,
+    });
+    const { url } = await server.start();
+    baseUrl = url;
+  });
+
+  afterEach(async () => {
+    await server.stop();
+    rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('serves /api/status with no trustCircle / connectivity and no nodes', async () => {
+    const res = await fetch(`${baseUrl}/api/status`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as {
+      service: { name: string };
+      nodes: unknown[];
+      trustCircle?: unknown;
+      connectivity?: unknown;
+    };
+    expect(body.service.name).toBe('cadre-host');
+    expect(body.nodes).toEqual([]);
+    expect(body.trustCircle).toBeUndefined();
+    expect(body.connectivity).toBeUndefined();
+  });
+
+  it('serves the donor surface: POST /grants-admin issues a grant', async () => {
+    const res = await fetch(`${baseUrl}/grants-admin`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ label: "Alice's cadre", maxNodes: 2 }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json() as { grant: { token: string; maxNodes: number } };
+    expect(body.grant.token).toBeTruthy();
+    expect(body.grant.maxNodes).toBe(2);
+  });
+
+  it('404s the founder-only NAT surface (GET /nat/status)', async () => {
+    const res = await fetch(`${baseUrl}/nat/status`);
+    expect(res.status).toBe(404);
+    const body = await res.json() as { error: { code: string } };
+    expect(body.error.code).toBe('not_found');
+  });
+
+  it('404s the founder-only trust-circle surface (/auth/*)', async () => {
+    const list = await fetch(`${baseUrl}/auth/trust-circle`);
+    expect(list.status).toBe(404);
+
+    const invite = await fetch(`${baseUrl}/auth/invites`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ label: 'Mom' }),
+    });
+    expect(invite.status).toBe(404);
+  });
+});

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

@@ -149,6 +149,23 @@ describe('/api/settings routes', () => {
     expect(body.error.message).toMatch(/uiPort/);
   });
 
+  it('PUT ownCadre returns 400 invalid_setting (install-time only)', async () => {
+    writeV2Config(dataDir);
+    app = Fastify();
+    registerErrorHandler(app);
+    registerSettingsRoutes(app, { settingsStore: new HostSettingsStore({ dataDir }), nat: fakeNat().svc });
+    const res = await app.inject({
+      method: 'PUT',
+      url: '/api/settings',
+      headers: { 'content-type': 'application/json' },
+      payload: JSON.stringify({ ownCadre: { enabled: true } }),
+    });
+    expect(res.statusCode).toBe(400);
+    const body = res.json() as { error: { code: string; message: string } };
+    expect(body.error.code).toBe('invalid_setting');
+    expect(body.error.message).toMatch(/ownCadre/);
+  });
+
   it('PUT unknown setting returns 400', async () => {
     writeV2Config(dataDir);
     app = Fastify();

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

@@ -91,6 +91,27 @@ describe('GET /api/status', () => {
     expect(body.update).toBeUndefined();
   });
 
+  it('omits trustCircle + connectivity in donor-only mode (no trust circle / NAT wired)', async () => {
+    app = Fastify();
+    registerErrorHandler(app);
+    registerStatusRoute(app, {
+      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 };
+      nodes: unknown[];
+      trustCircle?: unknown;
+      connectivity?: unknown;
+    };
+    expect(body.service.name).toBe('cadre-host');
+    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);

package/src/server/error-handler.ts

@@ -22,6 +22,21 @@
  *       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")
  */
 
@@ -31,6 +46,7 @@ import debug from 'debug';
 import { TrustCircleError, type TrustCircleErrorCode } from '../auth/types.js';
 import { NatError, type NatErrorCode } from '../nat/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');
 
@@ -57,6 +73,27 @@ const NAT_STATUS: Record<NatErrorCode, number> = {
   node_unavailable: 503,
 };
 
+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,
@@ -100,6 +137,12 @@ function classify(err: FastifyError): Classified {
   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 {

package/src/server/index.ts

@@ -22,6 +22,8 @@ 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 { 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';
@@ -35,6 +37,8 @@ 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 { registerGrantsAdminRoutes } from './routes/grants-admin.js';
+import { registerGrantsRoutes } from './routes/grants.js';
 import { HostSettingsStore } from './settings-store.js';
 
 export interface LocalUiServerOptions {
@@ -44,10 +48,33 @@ export interface LocalUiServerOptions {
   dataDir: string;
   /** Wired dependencies — all owned by the caller. */
   orchestrator: HostProcessOrchestrator;
-  trustCircle: TrustCircleService;
-  nat: NatService;
+  /**
+   * Trust-circle service — present only when the host runs its own personal
+   * cadre (`ownCadre.enabled`). Absent in donor-only mode, where `/auth/*`
+   * stays unmounted and 404s.
+   */
+  trustCircle?: TrustCircleService;
+  /**
+   * NAT service — present only when the host runs its own personal cadre.
+   * Absent in donor-only mode (loopback-only in v1), where `/nat/*` stays
+   * unmounted and 404s.
+   */
+  nat?: NatService;
   /** 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). 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. */
@@ -99,18 +126,33 @@ export function createLocalUiServer(opts: LocalUiServerOptions): LocalUiServer {
 
   registerStatusRoute(app, {
     orchestrator: opts.orchestrator,
-    trustCircle: opts.trustCircle,
-    nat: opts.nat,
+    ...(opts.trustCircle ? { trustCircle: opts.trustCircle } : {}),
+    ...(opts.nat ? { nat: opts.nat } : {}),
     ...(opts.update ? { update: opts.update } : {}),
   });
   registerNodesRoutes(app, { orchestrator: opts.orchestrator });
-  registerSettingsRoutes(app, { settingsStore, nat: opts.nat, ...(opts.update ? { update: opts.update } : {}) });
+  registerSettingsRoutes(app, { settingsStore, ...(opts.nat ? { nat: opts.nat } : {}), ...(opts.update ? { update: opts.update } : {}) });
 
-  registerTrustCircleRoutes(app, { handlers: createTrustCircleHandlers(opts.trustCircle), events });
-  registerNatRoutes(app, { handlers: createNatHandlers(opts.nat), events });
+  // Trust-circle + NAT surfaces exist only when the host runs its own personal
+  // cadre. In donor-only mode they're left unmounted, so `/auth/*` and `/nat/*`
+  // fall through to the static not-found handler and 404 (see static.ts).
+  if (opts.trustCircle) {
+    registerTrustCircleRoutes(app, { handlers: createTrustCircleHandlers(opts.trustCircle), events });
+  }
+  if (opts.nat) {
+    registerNatRoutes(app, { handlers: createNatHandlers(opts.nat), events });
+  }
   if (opts.update) {
     registerUpdateRoutes(app, { handlers: createUpdateHandlers(opts.update), events });
   }
+  if (opts.grants) {
+    registerGrantsAdminRoutes(app, { handlers: createGrantAdminHandlers(opts.grants) });
+    // 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.
@@ -147,16 +189,19 @@ export function createLocalUiServer(opts: LocalUiServerOptions): LocalUiServer {
       );
 
       // One-shot connectivity publish — the SPA will get a sane initial
-      // signal even if no settings have changed yet this session.
-      try {
-        const snap = opts.nat.getStatus();
-        events.publish({
-          type: 'connectivity-changed',
-          portMode: snap.portMode,
-          directReachability: snap.directReachability,
-        });
-      } catch {
-        // NatService.start may not have completed; harmless to skip.
+      // signal even if no settings have changed yet this session. Skipped in
+      // donor-only mode, where there is no NatService.
+      if (opts.nat) {
+        try {
+          const snap = opts.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

package/src/server/routes/grants-admin.ts

@@ -0,0 +1,41 @@
+/**
+ * Donation grant **admin** HTTP routes — thin adapters around
+ * `GrantAdminHandlers` (`createGrantAdminHandlers(service)`).
+ *
+ * Mount path: `/grants-admin` — the admin surface the `cadre-host grant` CLI
+ * targets. It is **loopback, no bearer**: same-machine admin, matching
+ * cadre-host's local-UI "no login" posture (see docs/cadre-host.md §
+ * Security posture). This is distinct from the grantee-facing `/grants`
+ * provisioning surface that carries the bearer gate — that arrives in the
+ * `2-donation-service` ticket.
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { GrantAdminHandlers } from '../../donation/types.js';
+
+export interface GrantsAdminRoutesOptions {
+  handlers: GrantAdminHandlers;
+}
+
+export function registerGrantsAdminRoutes(app: FastifyInstance, opts: GrantsAdminRoutesOptions): void {
+  const { handlers } = opts;
+
+  app.get('/grants-admin', async () => {
+    return handlers.listGrants();
+  });
+
+  app.post('/grants-admin', async (request) => {
+    const body = (request.body ?? {}) as { label?: unknown; maxNodes?: unknown; ttlMs?: unknown };
+    const label = typeof body.label === 'string' ? body.label : '';
+    const args: { label: string; maxNodes?: number; ttlMs?: number } = { label };
+    if (typeof body.maxNodes === 'number') args.maxNodes = body.maxNodes;
+    if (typeof body.ttlMs === 'number') args.ttlMs = body.ttlMs;
+    return handlers.postGrant(args);
+  });
+
+  app.delete<{ Params: { token: string } }>('/grants-admin/:token', async (request) => {
+    await handlers.deleteGrant(request.params.token);
+    return { ok: true };
+  });
+}

package/src/server/routes/grants.ts

@@ -0,0 +1,186 @@
+/**
+ * Grantee-facing donation routes — the HTTP surface an external cadre authority
+ * (a friend's phone) drives to have this host donate a node into *its* cadre.
+ *
+ * Mount path: `/grants`. Distinct from the loopback-only `/grants-admin` surface
+ * (issue/list/revoke, no bearer): this one is **bearer-gated** — every request
+ * carries `Authorization: Bearer <grant-token>`, and a grantee sees only the
+ * donations its own grant authorized (the single cross-grantee boundary,
+ * analogous to cadre-provider's per-customer ownership check).
+ *
+ * Reachability is out of scope here: in v1 this mounts on the loopback
+ * management server, same as the trust-circle / NAT surfaces. Physically exposing
+ * it to a remote phone is `backlog/feat-cadre-host-wan-grant-reachability`.
+ *
+ * Errors: handlers either send a `{ ok:false, error:{code,message} }` envelope
+ * inline (auth / body validation) or let the `DonationService` throw a
+ * `DonationError`, which `server/error-handler.ts` maps to the matching HTTP
+ * status and the same envelope.
+ */
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+
+import type { DonationService, DonationProvisionRequest } from '../../donation/donation-service.js';
+import type { DonationView, GrantValidator } from '../../donation/types.js';
+
+export interface GrantsRoutesOptions {
+  donations: DonationService;
+  /** Validates the presented bearer for non-provisioning ops (provision revalidates internally). */
+  grants: GrantValidator;
+}
+
+/** Uniform error envelope (matches `error-handler.ts` and the provider API). */
+function errorResponse(reply: FastifyReply, code: string, message: string, status: number) {
+  return reply.status(status).send({ ok: false, error: { code, message } });
+}
+
+/** Pull the `Bearer <token>` value out of the Authorization header, or undefined. */
+function parseBearer(header: string | undefined): string | undefined {
+  if (!header) return undefined;
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : undefined;
+}
+
+/** Map a grant denial reason to an HTTP status for the bearer gate. */
+function denyStatus(reason: string | undefined): number {
+  if (reason === 'expired' || reason === 'revoked') return 403;
+  return 401; // unknown_token / missing
+}
+
+/**
+ * Authenticate the grant bearer for a non-provisioning op (identity + not
+ * expired/revoked; no quota). Returns the token, or null after sending the
+ * failure response. Provision does its own quota-aware validation inside
+ * `DonationService.provision`.
+ */
+function authenticate(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  grants: GrantValidator,
+): string | null {
+  const token = parseBearer(request.headers.authorization);
+  if (!token) {
+    errorResponse(reply, 'unauthorized', 'Missing bearer grant token', 401);
+    return null;
+  }
+  const validation = grants.validate(token);
+  if (!validation.ok) {
+    const status = denyStatus(validation.reason);
+    // Keep the envelope code aligned with the status (and with the POST path,
+    // which surfaces an unknown token as `unauthorized`): 401 → unauthorized,
+    // 403 → forbidden. A 401 labelled `forbidden` is self-contradictory.
+    const code = status === 403 ? 'forbidden' : 'unauthorized';
+    errorResponse(reply, code, `Grant is ${validation.reason ?? 'invalid'}`, status);
+    return null;
+  }
+  return token;
+}
+
+/**
+ * Resolve a donation the presented grant owns. Returns the redacted view, or
+ * null after sending a 404 — an unknown id and one owned by a *different* grant
+ * are deliberately indistinguishable (a grantee never learns another grantee's
+ * donations exist).
+ */
+function requireOwned(
+  donations: DonationService,
+  id: string,
+  token: string,
+  reply: FastifyReply,
+): DonationView | null {
+  const donation = donations.get(id);
+  if (!donation || donation.grantToken !== token) {
+    errorResponse(reply, 'not_found', `No such donation: ${id}`, 404);
+    return null;
+  }
+  return donation;
+}
+
+export function registerGrantsRoutes(app: FastifyInstance, opts: GrantsRoutesOptions): void {
+  const { donations, grants } = opts;
+
+  // POST /grants — provision a donated node. The bearer's identity/expiry/
+  // revocation AND quota are validated inside provision(), which throws a
+  // DonationError (unauthorized / forbidden / quota_exceeded) the error handler
+  // maps. We only parse the bearer and validate the request body here.
+  app.post('/grants', async (request, reply) => {
+    const token = parseBearer(request.headers.authorization);
+    if (!token) {
+      return errorResponse(reply, 'unauthorized', 'Missing bearer grant token', 401);
+    }
+
+    const body = (request.body ?? {}) as Partial<DonationProvisionRequest>;
+    if (typeof body.partyId !== 'string' || body.partyId.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'partyId is required', 400);
+    }
+    if (!Array.isArray(body.bootstrapNodes) || body.bootstrapNodes.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'bootstrapNodes is required', 400);
+    }
+    if (!Array.isArray(body.ownerKeys) || body.ownerKeys.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'ownerKeys is required', 400);
+    }
+    if (body.profile !== undefined && body.profile !== 'storage' && body.profile !== 'transaction') {
+      return errorResponse(reply, 'invalid_request', 'profile must be "storage" or "transaction"', 400);
+    }
+
+    const donation = await donations.provision({
+      grantToken: token,
+      partyId: body.partyId,
+      bootstrapNodes: body.bootstrapNodes,
+      ownerKeys: body.ownerKeys,
+      ...(body.profile ? { profile: body.profile } : {}),
+    });
+    return reply.status(201).send({ ok: true, data: { donation } });
+  });
+
+  // GET /grants — list only the donations this grant authorized.
+  app.get('/grants', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    return reply.send({ ok: true, data: { donations: donations.list(token) } });
+  });
+
+  // GET /grants/:id — one donation (redacted), owned by this grant.
+  app.get<{ Params: { id: string } }>('/grants/:id', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    const donation = requireOwned(donations, request.params.id, token, reply);
+    if (!donation) return reply;
+    return reply.send({ ok: true, data: { donation } });
+  });
+
+  // GET /grants/:id/peer — live { peerId, multiaddrs } for the requester's addDrone.
+  app.get<{ Params: { id: string } }>('/grants/:id/peer', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+    const peer = await donations.getPeer(request.params.id);
+    return reply.send({ ok: true, data: peer });
+  });
+
+  // PUT /grants/:id/seed — apply the requester's phone-signed seed.
+  app.put<{ Params: { id: string } }>('/grants/:id/seed', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+
+    const body = (request.body ?? {}) as { seed?: unknown };
+    if (typeof body.seed !== 'string' || body.seed.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'seed is required', 400);
+    }
+    const result = await donations.applySeed(request.params.id, body.seed);
+    if (!result.success) {
+      return errorResponse(reply, 'seed_failed', result.error ?? 'Node rejected the seed', 502);
+    }
+    return reply.send({ ok: true, data: { peersAdded: result.peersAdded ?? 0 } });
+  });
+
+  // DELETE /grants/:id — terminate the donated node.
+  app.delete<{ Params: { id: string } }>('/grants/:id', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+    await donations.terminate(request.params.id);
+    return reply.send({ ok: true });
+  });
+}

package/src/server/routes/nodes.ts

@@ -6,10 +6,11 @@
  * `onStateChange` (forwarded by `createLocalUiServer.start`) — the route
  * handlers don't re-publish.
  *
- * start/restart are real for the admin's authority node (re-spawned from the
- * persisted `AuthoritySpawnConfig`). Generic per-member node spawn from saved
- * config is out of scope and returns `not_implemented`. Stop works for any
- * running node.
+ * start/restart are real for the admin's owner node (re-spawned from the
+ * persisted `OwnerSpawnConfig`). Generic node lifecycle is owned by the
+ * grantee-facing donation surface (`/grants`) — this route no longer spawns
+ * generic nodes; start/restart of a known non-owner node points the caller
+ * there. Stop works for any running node.
  */
 
 import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
@@ -83,17 +84,17 @@ export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptio
     return { ok: true };
   });
 
-  // start / restart: real for the admin's authority node (spawned from the
-  // persisted AuthoritySpawnConfig). Generic per-member node spawn from saved
-  // config is out of scope — those ids return a clear not_implemented; unknown
-  // ids 404.
+  // start / restart: real for the admin's owner node (spawned from the
+  // persisted OwnerSpawnConfig). Generic node lifecycle now belongs to the
+  // donation surface (/grants) — those ids return a clear not_implemented that
+  // points there; unknown ids 404.
   app.post<{ Params: { id: string } }>('/api/nodes/:id/start', async (request, reply) => {
     const { id } = request.params;
-    if (orchestrator.isAuthorityNode(id)) {
-      if (!orchestrator.hasAuthorityConfig()) {
-        return notImplemented(reply, `start ${id}: authority node has no saved spawn config.`);
+    if (orchestrator.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `start ${id}: owner node has no saved spawn config.`);
       }
-      const node = await orchestrator.ensureAuthorityNode();
+      const node = await orchestrator.ensureOwnerNode();
       return { ok: true, data: { node } };
     }
     return startRestartFallback(reply, orchestrator, id, 'start');
@@ -101,18 +102,18 @@ export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptio
 
   app.post<{ Params: { id: string } }>('/api/nodes/:id/restart', async (request, reply) => {
     const { id } = request.params;
-    if (orchestrator.isAuthorityNode(id)) {
-      if (!orchestrator.hasAuthorityConfig()) {
-        return notImplemented(reply, `restart ${id}: authority node has no saved spawn config.`);
+    if (orchestrator.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `restart ${id}: owner node has no saved spawn config.`);
       }
-      const node = await orchestrator.restartAuthorityNode();
+      const node = await orchestrator.restartOwnerNode();
       return { ok: true, data: { node } };
     }
     return startRestartFallback(reply, orchestrator, id, 'restart');
   });
 }
 
-/** 404 for unknown ids; 501 not_implemented for known non-authority nodes. */
+/** 404 for unknown ids; 501 not_implemented for known non-owner nodes. */
 function startRestartFallback(
   reply: import('fastify').FastifyReply,
   orchestrator: HostProcessOrchestrator,
@@ -127,7 +128,7 @@ function startRestartFallback(
   }
   return notImplemented(
     reply,
-    `${verb} ${id}: only the authority node is start/restart-able; generic node spawn is out of scope.`,
+    `${verb} ${id}: only the owner node is start/restart-able here; generic donated-node lifecycle is owned by the donation surface — use POST /grants to provision and DELETE /grants/:id to terminate.`,
   );
 }
 

package/src/server/routes/settings.ts

@@ -21,14 +21,19 @@ import type { NatService } from '../../nat/index.js';
 import type { UpdateService } from '../../update/index.js';
 import type { HostSettingsStore } from '../settings-store.js';
 
-const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version']);
+const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version', 'ownCadre']);
 
 const WRITABLE_TOP_KEYS = new Set<string>(['upnpEnabled', 'updates']);
 const WRITABLE_UPDATES_KEYS = new Set<string>(['autoApply', 'manifestUrl']);
 
 export interface SettingsRoutesOptions {
   settingsStore: HostSettingsStore;
-  nat: NatService;
+  /**
+   * Present only when the host runs its own personal cadre. In donor-only mode
+   * an `upnpEnabled` write still persists to host.config.json but has no running
+   * NatService to propagate into.
+   */
+  nat?: NatService;
   update?: UpdateService;
 }
 
@@ -58,7 +63,10 @@ export function registerSettingsRoutes(app: FastifyInstance, opts: SettingsRoute
       // takes effect immediately. NatService persists into nat.json — that's
       // independent of host.config.json's `upnpEnabled` (which the installer
       // uses on first run to seed nat.json). Update both for consistency.
-      await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+      // In donor-only mode there is no NatService — the write still persists.
+      if (nat) {
+        await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+      }
     }
     if ('updates' in body) {
       const updates = body.updates as { autoApply?: boolean; manifestUrl?: string };