@serfab/cadre-host 0.8.1 → 0.9.0

package/src/{authority/authority-node-client.ts → owner/owner-node-client.ts}

@@ -1,69 +1,70 @@
 /**
- * HTTP client for the authority node's loopback admin channel (the 6.6
+ * HTTP client for the owner node's loopback admin channel (the 6.6
  * `cadre-node-admin-channel` contract).
  *
  * cadre-host's manager process holds no in-process `CadreNode`; it spawns the
- * admin's authority node as a managed child (see `HostProcessOrchestrator`)
- * and delegates all authority/membership/identity operations to it over this
+ * admin's owner node as a managed child (see `HostProcessOrchestrator`)
+ * and delegates all owner/membership/identity operations to it over this
  * client. The client implements **both** trimmed `CadreNodeLike` interfaces —
  * the trust-circle one (`auth/trust-circle.ts`) and the NAT one
- * (`nat/nat-service.ts`) — plus `pushInviteAddresses`.
+ * (`nat/nat-service.ts`) — plus `pushInviteAddresses` and `addDrone` (the
+ * node-donation requester side).
  *
  * Transport: `Authorization: Bearer <token>` against
  * `http://127.0.0.1:<adminPort>`. Every response uses the cadre-provider
  * envelope `{ ok: true, data }` / `{ ok: false, error: { code, message } }`.
  * A refused connection, a transport error, or any non-2xx response surfaces
- * as {@link AuthorityNodeUnavailableError}; the trust-circle / NAT services
+ * as {@link OwnerNodeUnavailableError}; the trust-circle / NAT services
  * translate that into a `node_unavailable` domain error so the management API
  * returns a clear 503 rather than a raw 500.
  */
 
 import debug from 'debug';
-import type { CadreInvite } from '@serfab/cadre-core';
+import type { CadreInvite, DroneInitResult } from '@serfab/cadre-core';
 
-import type { AuthorityAdminEndpoint } from '../orchestrator/index.js';
+import type { OwnerAdminEndpoint } from '../orchestrator/index.js';
 import type { CadreNodeLike as TrustCircleCadreNodeLike } from '../auth/trust-circle.js';
 import type { CadreNodeLike as NatCadreNodeLike } from '../nat/nat-service.js';
 
-const log = debug('cadre:host:authority-client');
+const log = debug('cadre:host:owner-client');
 
 /**
- * Raised when the authority node's admin channel can't be reached or returns
+ * Raised when the owner node's admin channel can't be reached or returns
  * a non-success response. Carries the node's stable error `code` when one was
  * present in the envelope (e.g. `not_ready`, `not_authorized`).
  */
-export class AuthorityNodeUnavailableError extends Error {
+export class OwnerNodeUnavailableError extends Error {
   /** The admin-channel error code, when the node answered with an envelope. */
   readonly nodeCode?: string;
 
   constructor(message: string, nodeCode?: string) {
     super(message);
-    this.name = 'AuthorityNodeUnavailableError';
+    this.name = 'OwnerNodeUnavailableError';
     if (nodeCode !== undefined) this.nodeCode = nodeCode;
   }
 }
 
 /** Endpoint provided directly or via a getter (so it tracks re-spawns). */
 type EndpointSource =
-  | AuthorityAdminEndpoint
-  | (() => AuthorityAdminEndpoint | undefined)
+  | OwnerAdminEndpoint
+  | (() => OwnerAdminEndpoint | undefined)
   | undefined;
 
-export interface AuthorityNodeClientOptions {
+export interface OwnerNodeClientOptions {
   /** Fetch override for tests. Defaults to the global `fetch`. */
   fetch?: typeof fetch;
 }
 
-export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNodeLike {
+export class OwnerNodeClient implements TrustCircleCadreNodeLike, NatCadreNodeLike {
   private readonly endpointSource: EndpointSource;
   private readonly fetchImpl: typeof fetch;
 
   /**
    * @param endpoint Either a fixed `{ baseUrl, token }` or a getter returning
-   *   the current endpoint (pass `orchestrator.getAuthorityAdminEndpoint`
+   *   the current endpoint (pass `orchestrator.getOwnerAdminEndpoint`
    *   bound, so a restart's new bearer token is picked up automatically).
    */
-  constructor(endpoint: EndpointSource, opts: AuthorityNodeClientOptions = {}) {
+  constructor(endpoint: EndpointSource, opts: OwnerNodeClientOptions = {}) {
     this.endpointSource = endpoint;
     this.fetchImpl = opts.fetch ?? fetch;
   }
@@ -123,6 +124,23 @@ export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNo
     return data.member;
   }
 
+  /** Authorized-membership surface (excludes self) — see {@link listMembers} for the addressable one. */
+  async listAuthorizedMembers(): Promise<Array<{ peerId: string; multiaddr: string | null }>> {
+    const data = await this.request<{ members: Array<{ peerId: string; multiaddr: string | null }> }>(
+      'GET',
+      '/admin/authorized-members',
+    );
+    return data.members;
+  }
+
+  async isAuthorizedMember(peerId: string): Promise<boolean> {
+    const data = await this.request<{ member: boolean }>(
+      'GET',
+      `/admin/authorized-members/${encodeURIComponent(peerId)}`,
+    );
+    return data.member;
+  }
+
   // --- NAT CadreNodeLike ---
 
   async getPeerId(): Promise<string> {
@@ -135,6 +153,22 @@ export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNo
     return data.multiaddrs;
   }
 
+  // --- drone seeding (node-donation requester side) ---
+
+  /**
+   * Mint a seed authorizing a drone — a provider-hosted / donated node — to join
+   * this node's cadre. The node signs the seed with its own authority key; only
+   * the signed, public `encodedSeed` is returned (the private key never leaves
+   * the node). This is the requester ("phone") side of the node-donation flow:
+   * the donor host presents the returned seed to the donated node's `POST /seed`.
+   */
+  async addDrone(options: { dronePeerId: string; droneMultiaddrs: string[] }): Promise<DroneInitResult> {
+    return await this.request<DroneInitResult>('POST', '/admin/add-drone', {
+      dronePeerId: options.dronePeerId,
+      droneMultiaddrs: options.droneMultiaddrs,
+    });
+  }
+
   // --- push-model invite addresses ---
 
   /** Push the NAT-resolved addresses the node should embed in future invites. */
@@ -144,10 +178,10 @@ export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNo
 
   // --- internals ---
 
-  private resolveEndpoint(): AuthorityAdminEndpoint {
+  private resolveEndpoint(): OwnerAdminEndpoint {
     const ep = typeof this.endpointSource === 'function' ? this.endpointSource() : this.endpointSource;
     if (!ep) {
-      throw new AuthorityNodeUnavailableError('Authority node admin endpoint is not available');
+      throw new OwnerNodeUnavailableError('Owner node admin endpoint is not available');
     }
     return ep;
   }
@@ -167,7 +201,7 @@ export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNo
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       log('admin %s %s transport error: %s', method, path, message);
-      throw new AuthorityNodeUnavailableError(`Authority node unreachable: ${message}`);
+      throw new OwnerNodeUnavailableError(`Owner node unreachable: ${message}`);
     }
 
     const envelope = await this.parseEnvelope(res);
@@ -175,7 +209,7 @@ export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNo
       const code = envelope.error?.code;
       const message = envelope.error?.message ?? `admin ${method} ${path} → HTTP ${res.status}`;
       log('admin %s %s failed: [%s] %s', method, path, code ?? res.status, message);
-      throw new AuthorityNodeUnavailableError(message, code);
+      throw new OwnerNodeUnavailableError(message, code);
     }
     return envelope.data as T;
   }

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

@@ -4,6 +4,7 @@ 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', () => {
@@ -24,6 +25,10 @@ describe('error handler', () => {
       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

@@ -21,7 +21,7 @@ interface FakeOrchestrator extends HostProcessOrchestrator {
 
 function fakeOrchestrator(
   initial: ManagedNodeInfo[] = [],
-  opts: { authorityId?: string; hasAuthorityConfig?: boolean } = {},
+  opts: { ownerId?: string; hasOwnerConfig?: boolean } = {},
 ): FakeOrchestrator {
   const nodes = new Map(initial.map((n) => [n.dockerId, n]));
   const listeners = new Set<NodeStateListener>();
@@ -41,21 +41,21 @@ function fakeOrchestrator(
       for (const n of nodes.values()) if (n.id === id) return n.dockerId;
       return undefined;
     },
-    isAuthorityNode: (id: string) => {
-      if (!opts.authorityId) return false;
+    isOwnerNode: (id: string) => {
+      if (!opts.ownerId) return false;
       const node = findById(id);
-      return id === opts.authorityId || node?.id === opts.authorityId;
+      return id === opts.ownerId || node?.id === opts.ownerId;
     },
-    hasAuthorityConfig: () => opts.hasAuthorityConfig ?? false,
-    ensureAuthorityNode: async () => {
+    hasOwnerConfig: () => opts.hasOwnerConfig ?? false,
+    ensureOwnerNode: async () => {
       counters.ensured++;
-      const node = opts.authorityId ? findById(opts.authorityId) : undefined;
-      return node ?? { id: opts.authorityId, status: 'running' } as unknown as ManagedNodeInfo;
+      const node = opts.ownerId ? findById(opts.ownerId) : undefined;
+      return node ?? { id: opts.ownerId, status: 'running' } as unknown as ManagedNodeInfo;
     },
-    restartAuthorityNode: async () => {
+    restartOwnerNode: async () => {
       counters.restarted++;
-      const node = opts.authorityId ? findById(opts.authorityId) : undefined;
-      return node ?? { id: opts.authorityId, status: 'running' } as unknown as ManagedNodeInfo;
+      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) => {
@@ -171,14 +171,14 @@ describe('/api/nodes routes', () => {
     ]);
   });
 
-  it('POST /api/nodes/:id/start on a non-authority node 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 on a non-authority node 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);
   });
@@ -191,9 +191,9 @@ describe('/api/nodes routes', () => {
   });
 });
 
-describe('/api/nodes — authority node start/restart', () => {
-  const AUTHORITY_NODE: ManagedNodeInfo = {
-    id: 'authority',
+describe('/api/nodes — owner node start/restart', () => {
+  const OWNER_NODE: ManagedNodeInfo = {
+    id: 'owner',
     dockerId: '999:tok',
     partyId: 'install-id',
     profile: 'storage',
@@ -201,7 +201,7 @@ describe('/api/nodes — authority node start/restart', () => {
     spawnedAt: '2025-01-01T00:00:00Z',
     workdir: '',
     ports: { health: 1, metrics: 2, p2p: 4555, admin: 3 },
-    authority: true,
+    owner: true,
   };
 
   let app: ReturnType<typeof Fastify>;
@@ -210,30 +210,30 @@ describe('/api/nodes — authority node start/restart', () => {
   beforeEach(() => {
     app = Fastify();
     registerErrorHandler(app);
-    orchestrator = fakeOrchestrator([AUTHORITY_NODE], { authorityId: 'authority', hasAuthorityConfig: true });
+    orchestrator = fakeOrchestrator([OWNER_NODE], { ownerId: 'owner', hasOwnerConfig: true });
     registerNodesRoutes(app, { orchestrator });
   });
 
   afterEach(async () => { await app.close(); });
 
-  it('start ensures the authority node', async () => {
-    const res = await app.inject({ method: 'POST', url: '/api/nodes/authority/start' });
+  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 authority node', async () => {
-    const res = await app.inject({ method: 'POST', url: '/api/nodes/authority/restart' });
+  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 authority config', async () => {
+  it('start returns 501 when there is no saved owner config', async () => {
     const app2 = Fastify();
     registerErrorHandler(app2);
-    const orch2 = fakeOrchestrator([AUTHORITY_NODE], { authorityId: 'authority', hasAuthorityConfig: false });
+    const orch2 = fakeOrchestrator([OWNER_NODE], { ownerId: 'owner', hasOwnerConfig: false });
     registerNodesRoutes(app2, { orchestrator: orch2 });
-    const res = await app2.inject({ method: 'POST', url: '/api/nodes/authority/start' });
+    const res = await app2.inject({ method: 'POST', url: '/api/nodes/owner/start' });
     expect(res.statusCode).toBe(501);
     await app2.close();
   });