@serfab/cadre-host 0.8.1 → 0.9.0

package/src/orchestrator/host-process-orchestrator.ts

@@ -30,7 +30,7 @@ import type { PushCredentials } from '@serfab/cadre-core';
 import {
   decodeDockerId,
   encodeDockerId,
-  type AuthoritySpawnConfig,
+  type OwnerSpawnConfig,
   type Handle,
   type HostProcessConfig,
   type ManagedNodeInfo,
@@ -53,11 +53,11 @@ const STARTUP_TOKEN_FILE = '.startup-token';
 const CONFIG_FILE = 'cadre.json';
 const LIVENESS_POLL_MS = 100;
 
-/** Fixed friendly id for the admin's authority node. */
-export const AUTHORITY_CONTAINER_ID = 'authority';
+/** Fixed friendly id for the admin's owner node. */
+export const OWNER_CONTAINER_ID = 'owner';
 
-/** Endpoint + bearer for the authority node's loopback admin channel (6.6). */
-export interface AuthorityAdminEndpoint {
+/** Endpoint + bearer for the owner node's loopback admin channel (6.6). */
+export interface OwnerAdminEndpoint {
   /** e.g. `http://127.0.0.1:<adminPort>`. */
   baseUrl: string;
   /** The child's `CADRE_STARTUP_TOKEN`, used as the admin bearer secret. */
@@ -108,8 +108,8 @@ export class HostProcessOrchestrator implements Orchestrator {
   private readonly pushResolver?: PushCredentialsResolver;
   /** State-change listeners — invoked when a handle's alive state changes. */
   private readonly stateListeners = new Set<NodeStateListener>();
-  /** Persisted spawn config for the authority node (re-spawn on demand). */
-  private authorityConfig?: AuthoritySpawnConfig;
+  /** Persisted spawn config for the owner node (re-spawn on demand). */
+  private ownerConfig?: OwnerSpawnConfig;
 
   constructor(private readonly cfg: HostProcessConfig) {
     this.rootDir = resolvePath(cfg.rootDir);
@@ -135,7 +135,7 @@ export class HostProcessOrchestrator implements Orchestrator {
    */
   async init(): Promise<void> {
     const state = this.stateStore.load();
-    this.authorityConfig = state.authorityConfig;
+    this.ownerConfig = state.ownerConfig;
     for (const persisted of state.handles) {
       const alive = isPidAlive(persisted.pid) && tokenMatches(persisted.workdir, persisted.startupToken);
       const handle: Handle = {
@@ -148,7 +148,7 @@ export class HostProcessOrchestrator implements Orchestrator {
         spawnedAt: persisted.spawnedAt,
         partyId: persisted.partyId,
         profile: persisted.profile,
-        ...(persisted.authority ? { authority: true } : {}),
+        ...(persisted.owner ? { owner: true } : {}),
         alive,
       };
       this.handles.set(handle.dockerId, handle);
@@ -224,17 +224,30 @@ export class HostProcessOrchestrator implements Orchestrator {
       p2p: this.portAllocator.allocate(),
       admin: this.portAllocator.allocate(),
     };
+    // A node started with pinned owner keys belongs to a FOREIGN cadre (the
+    // node-donation flow: it trusts the requester's owner key, not the host's).
+    // The host's FCM/APNs credentials are minted for the host owner's own app
+    // and are meaningless to a foreign cadre — so donated nodes get NO push
+    // block. (Per-grantee push creds would be a future ticket; none in v1.)
+    const foreignParty = (request.pinnedOwnerKeys?.length ?? 0) > 0;
     // Only storage-profile nodes participate in strands and thus fan out push
     // wakes — a transaction-only node need not carry credentials.
-    const push = request.profile === 'storage' ? await this.resolvePush() : undefined;
+    const push = request.profile === 'storage' && !foreignParty ? await this.resolvePush() : undefined;
+    // Pinned owner key(s) reach the child via CADRE_OWNER_KEYS (comma-separated);
+    // `cadre-cli start` unions it into its cold-start pinnedKeyTrustPolicy so the
+    // node will accept the foreign-authority-signed seed presented via POST /seed.
+    const extraEnv = request.pinnedOwnerKeys?.length
+      ? { CADRE_OWNER_KEYS: request.pinnedOwnerKeys.join(',') }
+      : undefined;
     return this.launchChild({
       containerId: request.containerId,
       partyId: request.partyId,
       profile: request.profile,
       ports,
-      authority: false,
+      owner: false,
       buildConfig: (workdir) => this.buildChildConfig(request, workdir, push),
       extraArgs: [],
+      ...(extraEnv ? { extraEnv } : {}),
       ...(request.resources?.memoryLimit ? { memoryLimit: request.resources.memoryLimit } : {}),
     });
   }
@@ -261,32 +274,32 @@ export class HostProcessOrchestrator implements Orchestrator {
   }
 
   /**
-   * Ensure the admin's authority node is running, spawning it if absent or
+   * Ensure the admin's owner node is running, spawning it if absent or
    * dead. Idempotent: a second call with the node already alive returns the
    * existing handle without launching a second child. The spawn parameters
    * are persisted so a later `/api/nodes/:id/{start,restart}` (or an
    * orchestrator restart) can re-spawn it without re-supplying them.
    *
-   * The authority node is spawned as `cadre-cli start --authority
+   * The owner node is spawned as `cadre-cli start --owner
    * --admin-port <p> --identity-protobuf <identityPath>` so it carries the
    * host's libp2p identity, founds/joins the control network, and exposes the
    * loopback admin channel the manager delegates to.
    */
-  async ensureAuthorityNode(cfg?: AuthoritySpawnConfig): Promise<ManagedNodeInfo> {
-    const config = cfg ?? this.authorityConfig;
+  async ensureOwnerNode(cfg?: OwnerSpawnConfig): Promise<ManagedNodeInfo> {
+    const config = cfg ?? this.ownerConfig;
     if (!config) {
-      throw new Error('ensureAuthorityNode: no authority config supplied and none persisted');
+      throw new Error('ensureOwnerNode: no owner config supplied and none persisted');
     }
-    this.authorityConfig = config;
+    this.ownerConfig = config;
 
-    const existing = this.findAuthorityHandle();
+    const existing = this.findOwnerHandle();
     if (existing && isPidAlive(existing.pid) && tokenMatches(existing.workdir, existing.startupToken)) {
       this.persist();
       return toNodeInfo(existing);
     }
     if (existing) {
       // Drop the stale handle and release its ports — but DO NOT delete the
-      // workdir: the authority node's control-DB storage lives there and must
+      // workdir: the owner node's control-DB storage lives there and must
       // survive a restart. launchChild reuses the same workdir.
       this.releasePorts(existing.ports);
       this.handles.delete(existing.dockerId);
@@ -300,7 +313,7 @@ export class HostProcessOrchestrator implements Orchestrator {
       health: this.portAllocator.allocate(),
       metrics: this.portAllocator.allocate(),
       admin: this.portAllocator.allocate(),
-      // The authority node must listen on the configured libp2p port so the
+      // The owner node must listen on the configured libp2p port so the
       // NAT mapping (external → internal) lands on it. That port is outside
       // the managed range, so markUsed is a harmless no-op.
       p2p: config.libp2pPort,
@@ -308,21 +321,21 @@ export class HostProcessOrchestrator implements Orchestrator {
     this.portAllocator.markUsed(config.libp2pPort);
 
     const result = this.launchChild({
-      containerId: AUTHORITY_CONTAINER_ID,
+      containerId: OWNER_CONTAINER_ID,
       partyId: config.partyId,
       profile,
       ports,
-      authority: true,
-      buildConfig: (workdir) => this.buildAuthorityChildConfig(config, profile, workdir, push),
-      extraArgs: ['--authority', '--admin-port', String(ports.admin), '--identity-protobuf', config.identityPath],
+      owner: true,
+      buildConfig: (workdir) => this.buildOwnerChildConfig(config, profile, workdir, push),
+      extraArgs: ['--owner', '--admin-port', String(ports.admin), '--identity-protobuf', config.identityPath],
     });
     const handle = this.handles.get(result.dockerId)!;
     return toNodeInfo(handle);
   }
 
-  /** Endpoint + bearer for the authority node's admin channel, if spawned. */
-  getAuthorityAdminEndpoint(): AuthorityAdminEndpoint | undefined {
-    const handle = this.findAuthorityHandle();
+  /** Endpoint + bearer for the owner node's admin channel, if spawned. */
+  getOwnerAdminEndpoint(): OwnerAdminEndpoint | undefined {
+    const handle = this.findOwnerHandle();
     if (!handle) return undefined;
     return {
       baseUrl: `http://127.0.0.1:${handle.ports.admin}`,
@@ -330,41 +343,41 @@ export class HostProcessOrchestrator implements Orchestrator {
     };
   }
 
-  /** Whether spawn parameters for the authority node are known (persisted). */
-  hasAuthorityConfig(): boolean {
-    return this.authorityConfig !== undefined;
+  /** Whether spawn parameters for the owner node are known (persisted). */
+  hasOwnerConfig(): boolean {
+    return this.ownerConfig !== undefined;
   }
 
-  /** Whether the given friendly/docker id refers to the authority node. */
-  isAuthorityNode(idOrDockerId: string): boolean {
-    if (idOrDockerId === AUTHORITY_CONTAINER_ID) return true;
+  /** Whether the given friendly/docker id refers to the owner node. */
+  isOwnerNode(idOrDockerId: string): boolean {
+    if (idOrDockerId === OWNER_CONTAINER_ID) return true;
     const direct = this.handles.get(idOrDockerId);
-    if (direct?.authority) return true;
+    if (direct?.owner) return true;
     for (const h of this.handles.values()) {
-      if (h.authority && h.containerId === idOrDockerId) return true;
+      if (h.owner && h.containerId === idOrDockerId) return true;
     }
     return false;
   }
 
-  /** Stop the authority node (if running). Used on graceful shutdown. */
-  async stopAuthorityNode(): Promise<void> {
-    const handle = this.findAuthorityHandle();
+  /** Stop the owner node (if running). Used on graceful shutdown. */
+  async stopOwnerNode(): Promise<void> {
+    const handle = this.findOwnerHandle();
     if (handle && isPidAlive(handle.pid)) {
       await this.stopContainer(handle.dockerId);
     }
   }
 
-  /** Stop the authority node (if running), then re-spawn it from saved config. */
-  async restartAuthorityNode(): Promise<ManagedNodeInfo> {
-    const handle = this.findAuthorityHandle();
+  /** Stop the owner node (if running), then re-spawn it from saved config. */
+  async restartOwnerNode(): Promise<ManagedNodeInfo> {
+    const handle = this.findOwnerHandle();
     if (handle && isPidAlive(handle.pid)) {
       await this.stopContainer(handle.dockerId);
     }
-    return this.ensureAuthorityNode();
+    return this.ensureOwnerNode();
   }
 
   /**
-   * Core spawn mechanics shared by `createContainer` and `ensureAuthorityNode`.
+   * Core spawn mechanics shared by `createContainer` and `ensureOwnerNode`.
    * The caller has already allocated `ports`. Releases the ports on a
    * synchronous spawn failure.
    */
@@ -373,9 +386,11 @@ export class HostProcessOrchestrator implements Orchestrator {
     partyId: string;
     profile: 'storage' | 'transaction';
     ports: NodePorts;
-    authority: boolean;
+    owner: boolean;
     buildConfig: (workdir: string) => Record<string, unknown>;
     extraArgs: string[];
+    /** Extra env vars merged into the child's environment (e.g. CADRE_OWNER_KEYS). */
+    extraEnv?: Record<string, string>;
     memoryLimit?: string;
   }): OrchestratorCreateResult {
     const { containerId, ports } = opts;
@@ -405,6 +420,9 @@ export class HostProcessOrchestrator implements Orchestrator {
 
     const env: NodeJS.ProcessEnv = {
       ...process.env,
+      // Caller-supplied extras first — the fixed per-child vars below always win
+      // so extraEnv can never clobber the seed/startup tokens or port wiring.
+      ...opts.extraEnv,
       CADRE_STARTUP_TOKEN: token,
       CADRE_HEALTH_PORT: String(ports.health),
       CADRE_METRICS_PORT: String(ports.metrics),
@@ -472,7 +490,7 @@ export class HostProcessOrchestrator implements Orchestrator {
       spawnedAt: new Date().toISOString(),
       partyId: opts.partyId,
       profile: opts.profile,
-      ...(opts.authority ? { authority: true } : {}),
+      ...(opts.owner ? { owner: true } : {}),
       child,
       alive: true,
     };
@@ -502,10 +520,10 @@ export class HostProcessOrchestrator implements Orchestrator {
     };
   }
 
-  /** Locate the authority node's handle, if one has been spawned. */
-  private findAuthorityHandle(): Handle | undefined {
+  /** Locate the owner node's handle, if one has been spawned. */
+  private findOwnerHandle(): Handle | undefined {
     for (const h of this.handles.values()) {
-      if (h.authority || h.containerId === AUTHORITY_CONTAINER_ID) return h;
+      if (h.owner || h.containerId === OWNER_CONTAINER_ID) return h;
     }
     return undefined;
   }
@@ -688,12 +706,20 @@ export class HostProcessOrchestrator implements Orchestrator {
   }
 
   /**
-   * Child config for the authority node. It founds/joins the control network
-   * for `partyId` (no bootstrap peers — it is the founding node), and carries
-   * the host identity via `--identity-protobuf` (passed as a spawn arg).
+   * Child config for the **host's own personal cadre** owner node — the opt-in
+   * "founder" persona spawned only when `ownCadre.enabled` (see
+   * docs/cadre-host.md § Two roles: donor and founder). It founds/joins the
+   * control network for the host's own `partyId` (no bootstrap peers — it is the
+   * founding node of the host's *own* cadre) and carries the host identity via
+   * `--identity-protobuf` (passed as a spawn arg).
+   *
+   * This is NOT the node cadre-host donates to a requester. Donated nodes are
+   * generic (`createContainer` / `buildChildConfig`): they join the
+   * **requester's** cadre via bootstrap peers and pin the *requester's* owner
+   * key — they never run a host genesis.
    */
-  private buildAuthorityChildConfig(
-    cfg: AuthoritySpawnConfig,
+  private buildOwnerChildConfig(
+    cfg: OwnerSpawnConfig,
     profile: 'storage' | 'transaction',
     workdir: string,
     push?: PushCredentials,
@@ -709,10 +735,12 @@ export class HostProcessOrchestrator implements Orchestrator {
     if (profile === 'storage') {
       config.storage = { type: 'file', path: join(workdir, 'storage') };
     }
-    // The always-on authority/storage node participates in strands, so it owns
-    // the push-wake fan-out when credentials are configured. Written into
-    // cadre.json (same host trust boundary as the workdir's control-DB); keys
-    // are never logged — only the redacted presence line in resolvePush.
+    // The host-own-cadre owner/storage node participates in strands, so it owns
+    // the push-wake fan-out when credentials are configured. (Donated nodes
+    // belong to foreign cadres and get NO host push block — see the donor path.)
+    // Written into cadre.json (same host trust boundary as the workdir's
+    // control-DB); keys are never logged — only the redacted presence line in
+    // resolvePush.
     if (push) config.push = push;
     return config;
   }
@@ -721,7 +749,7 @@ export class HostProcessOrchestrator implements Orchestrator {
     const state: PersistedState = {
       version: 1,
       handles: [...this.handles.values()].map((h) => this.toPersisted(h)),
-      ...(this.authorityConfig ? { authorityConfig: this.authorityConfig } : {}),
+      ...(this.ownerConfig ? { ownerConfig: this.ownerConfig } : {}),
     };
     this.stateStore.save(state);
   }
@@ -749,7 +777,7 @@ export class HostProcessOrchestrator implements Orchestrator {
       spawnedAt: h.spawnedAt,
       partyId: h.partyId,
       profile: h.profile,
-      ...(h.authority ? { authority: true } : {}),
+      ...(h.owner ? { owner: true } : {}),
     };
   }
 }
@@ -764,7 +792,7 @@ function toNodeInfo(h: Handle): ManagedNodeInfo {
     spawnedAt: h.spawnedAt,
     workdir: h.workdir,
     ports: { ...h.ports },
-    ...(h.authority ? { authority: true } : {}),
+    ...(h.owner ? { owner: true } : {}),
   };
 }
 

package/src/orchestrator/index.ts

@@ -1,10 +1,10 @@
-export { HostProcessOrchestrator, AUTHORITY_CONTAINER_ID } from './host-process-orchestrator.js';
-export type { AuthorityAdminEndpoint } from './host-process-orchestrator.js';
+export { HostProcessOrchestrator, OWNER_CONTAINER_ID } from './host-process-orchestrator.js';
+export type { OwnerAdminEndpoint } from './host-process-orchestrator.js';
 export type {
   HostProcessConfig,
   ManagedNodeInfo,
   NodeStateListener,
   NodePorts,
-  AuthoritySpawnConfig,
+  OwnerSpawnConfig,
 } from './types.js';
 export type { PersistedHandle } from './state-store.js';

package/src/orchestrator/state-store.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from '
 import { dirname, join } from 'node:path';
 import debug from 'debug';
 
-import type { AuthoritySpawnConfig, NodePorts } from './types.js';
+import type { OwnerSpawnConfig, NodePorts } from './types.js';
 
 const log = debug('cadre:host:state-store');
 
@@ -21,15 +21,15 @@ export interface PersistedHandle {
   spawnedAt: string;          // ISO timestamp
   partyId: string;
   profile: 'storage' | 'transaction';
-  /** True for the admin's authority node. */
-  authority?: boolean;
+  /** True for the admin's owner node. */
+  owner?: boolean;
 }
 
 export interface PersistedState {
   version: 1;
   handles: PersistedHandle[];
-  /** Spawn parameters for the authority node, so it can be re-spawned on demand. */
-  authorityConfig?: AuthoritySpawnConfig;
+  /** Spawn parameters for the owner node, so it can be re-spawned on demand. */
+  ownerConfig?: OwnerSpawnConfig;
 }
 
 const STATE_VERSION = 1;
@@ -57,7 +57,7 @@ export class StateStore {
       return {
         version: STATE_VERSION,
         handles: parsed.handles,
-        ...(parsed.authorityConfig ? { authorityConfig: parsed.authorityConfig } : {}),
+        ...(parsed.ownerConfig ? { ownerConfig: parsed.ownerConfig } : {}),
       };
     } catch (err) {
       // A corrupt state file is operationally significant — surviving children
@@ -74,7 +74,7 @@ export class StateStore {
       {
         version: STATE_VERSION,
         handles: state.handles,
-        ...(state.authorityConfig ? { authorityConfig: state.authorityConfig } : {}),
+        ...(state.ownerConfig ? { ownerConfig: state.ownerConfig } : {}),
       },
       null,
       2,

package/src/orchestrator/types.ts

@@ -47,7 +47,7 @@ export interface NodePorts {
   health: number;
   metrics: number;
   p2p: number;
-  /** Loopback admin-channel port. Bound only by the authority node. */
+  /** Loopback admin-channel port. Bound only by the owner node. */
   admin: number;
 }
 
@@ -62,8 +62,8 @@ export interface Handle {
   spawnedAt: string;
   partyId: string;
   profile: 'storage' | 'transaction';
-  /** True for the admin's authority node (binds the admin channel). */
-  authority?: boolean;
+  /** True for the admin's owner node (binds the admin channel). */
+  owner?: boolean;
   /** Live ChildProcess reference; absent after re-attach via init(). */
   child?: ChildProcess;
   /** Marked false when init() finds the PID dead or token mismatched. */
@@ -83,16 +83,16 @@ export interface ManagedNodeInfo {
   spawnedAt: string;
   workdir: string;
   ports: NodePorts;
-  /** True for the admin's authority node. */
-  authority?: boolean;
+  /** True for the admin's owner node. */
+  owner?: boolean;
 }
 
 /**
- * Persisted spawn parameters for the admin's authority node. Stored alongside
- * the handles so an orchestrator restart can re-spawn the authority node from
+ * Persisted spawn parameters for the admin's owner node. Stored alongside
+ * the handles so an orchestrator restart can re-spawn the owner node from
  * `/api/nodes/:id/{start,restart}` without the caller re-supplying them.
  */
-export interface AuthoritySpawnConfig {
+export interface OwnerSpawnConfig {
   /** Absolute path to the host's libp2p protobuf identity (`identity.key`). */
   identityPath: string;
   /** Control-network partyId (the host's installId). */

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

@@ -1,8 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import http from 'node:http';
 
-import { AuthorityNodeClient, AuthorityNodeUnavailableError } from '../authority-node-client.js';
-import type { AuthorityAdminEndpoint } from '../../orchestrator/index.js';
+import { OwnerNodeClient, OwnerNodeUnavailableError } from '../owner-node-client.js';
+import type { OwnerAdminEndpoint } from '../../orchestrator/index.js';
 
 /**
  * Stub HTTP server matching the 6.6 admin contract. Records the last request
@@ -52,16 +52,16 @@ afterEach(async () => {
   await new Promise<void>((resolve) => server.close(() => resolve()));
 });
 
-function makeClient(): AuthorityNodeClient {
-  const endpoint: AuthorityAdminEndpoint = { baseUrl, token: TOKEN };
-  return new AuthorityNodeClient(endpoint);
+function makeClient(): OwnerNodeClient {
+  const endpoint: OwnerAdminEndpoint = { baseUrl, token: TOKEN };
+  return new OwnerNodeClient(endpoint);
 }
 
-describe('AuthorityNodeClient', () => {
+describe('OwnerNodeClient', () => {
   it('createInvite POSTs /admin/invites with bearer + body and unwraps data', async () => {
     responder = () => ({
       status: 200,
-      payload: { ok: true, data: { invite: { partyId: 'p', authorityAddrs: [], token: 't', createdAt: 1 }, encodedInvite: 'enc' } },
+      payload: { ok: true, data: { invite: { partyId: 'p', ownerAddrs: [], token: 't', createdAt: 1 }, encodedInvite: 'enc' } },
     });
     const client = makeClient();
     const result = await client.createInvite('t', 60_000);
@@ -75,7 +75,7 @@ describe('AuthorityNodeClient', () => {
 
   it('acceptPhone POSTs /admin/accept-phone', async () => {
     const client = makeClient();
-    await client.acceptPhone({ phonePeerId: '12D3KooWX', token: 't' }, { partyId: 'p', authorityAddrs: [], token: 't', createdAt: 1 });
+    await client.acceptPhone({ phonePeerId: '12D3KooWX', token: 't' }, { partyId: 'p', ownerAddrs: [], token: 't', createdAt: 1 });
     expect(last?.method).toBe('POST');
     expect(last?.path).toBe('/admin/accept-phone');
     const body = JSON.parse(last!.body);
@@ -106,6 +106,22 @@ describe('AuthorityNodeClient', () => {
     expect(last?.path).toBe('/admin/members/peer-1');
   });
 
+  it('listAuthorizedMembers GETs /admin/authorized-members and returns the array', async () => {
+    responder = () => ({ status: 200, payload: { ok: true, data: { members: [{ peerId: 'b', multiaddr: null }] } } });
+    const client = makeClient();
+    const members = await client.listAuthorizedMembers();
+    expect(last?.method).toBe('GET');
+    expect(last?.path).toBe('/admin/authorized-members');
+    expect(members).toEqual([{ peerId: 'b', multiaddr: null }]);
+  });
+
+  it('isAuthorizedMember GETs /admin/authorized-members/:peerId and returns the boolean', async () => {
+    responder = () => ({ status: 200, payload: { ok: true, data: { member: false } } });
+    const client = makeClient();
+    expect(await client.isAuthorizedMember('peer-2')).toBe(false);
+    expect(last?.path).toBe('/admin/authorized-members/peer-2');
+  });
+
   it('getPeerId GETs /admin/identity', async () => {
     responder = () => ({ status: 200, payload: { ok: true, data: { peerId: '12D3KooWHost', partyId: 'party' } } });
     const client = makeClient();
@@ -128,22 +144,34 @@ describe('AuthorityNodeClient', () => {
     expect(JSON.parse(last!.body)).toEqual({ addresses: ['/dns4/h/tcp/1/p2p/x'] });
   });
 
+  it('addDrone POSTs /admin/add-drone with body and unwraps the seed result', async () => {
+    responder = () => ({ status: 200, payload: { ok: true, data: { seed: { partyId: 'p', peers: [] }, encodedSeed: 'enc-seed' } } });
+    const client = makeClient();
+    const result = await client.addDrone({ dronePeerId: '12D3KooWDrone', droneMultiaddrs: ['/ip4/10.0.0.9/tcp/4001'] });
+
+    expect(result.encodedSeed).toBe('enc-seed');
+    expect(last?.method).toBe('POST');
+    expect(last?.path).toBe('/admin/add-drone');
+    expect(last?.auth).toBe(`Bearer ${TOKEN}`);
+    expect(JSON.parse(last!.body)).toEqual({ dronePeerId: '12D3KooWDrone', droneMultiaddrs: ['/ip4/10.0.0.9/tcp/4001'] });
+  });
+
   it('encodeInvite mirrors cadre-core base64url(JSON)', () => {
     const client = makeClient();
-    const invite = { partyId: 'p', authorityAddrs: [], token: 't', createdAt: 1 };
+    const invite = { partyId: 'p', ownerAddrs: [], token: 't', createdAt: 1 };
     const encoded = client.encodeInvite(invite);
     const decoded = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
     expect(decoded).toEqual(invite);
   });
 
-  it('maps a non-2xx response to AuthorityNodeUnavailableError carrying the code', async () => {
+  it('maps a non-2xx response to OwnerNodeUnavailableError carrying the code', async () => {
     responder = () => ({ status: 503, payload: { ok: false, error: { code: 'not_ready', message: 'node booting' } } });
     const client = makeClient();
-    await expect(client.getPeerId()).rejects.toBeInstanceOf(AuthorityNodeUnavailableError);
+    await expect(client.getPeerId()).rejects.toBeInstanceOf(OwnerNodeUnavailableError);
     await expect(client.getPeerId()).rejects.toMatchObject({ nodeCode: 'not_ready' });
   });
 
-  it('maps a refused connection to AuthorityNodeUnavailableError', async () => {
+  it('maps a refused connection to OwnerNodeUnavailableError', async () => {
     // Bind a throwaway server to claim a port, then close it so the address
     // is guaranteed refused.
     const tmp = http.createServer();
@@ -155,12 +183,12 @@ describe('AuthorityNodeClient', () => {
     });
     await new Promise<void>((resolve) => tmp.close(() => resolve()));
 
-    const client = new AuthorityNodeClient({ baseUrl: `http://127.0.0.1:${closedPort}`, token: TOKEN });
-    await expect(client.getPeerId()).rejects.toBeInstanceOf(AuthorityNodeUnavailableError);
+    const client = new OwnerNodeClient({ baseUrl: `http://127.0.0.1:${closedPort}`, token: TOKEN });
+    await expect(client.getPeerId()).rejects.toBeInstanceOf(OwnerNodeUnavailableError);
   });
 
-  it('throws AuthorityNodeUnavailableError when the endpoint is undefined', async () => {
-    const client = new AuthorityNodeClient(() => undefined);
-    await expect(client.getPeerId()).rejects.toBeInstanceOf(AuthorityNodeUnavailableError);
+  it('throws OwnerNodeUnavailableError when the endpoint is undefined', async () => {
+    const client = new OwnerNodeClient(() => undefined);
+    await expect(client.getPeerId()).rejects.toBeInstanceOf(OwnerNodeUnavailableError);
   });
 });

package/src/owner/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Owner-node delegation surface for cadre-host.
+ *
+ * The manager process spawns the admin's owner cadre node (via
+ * `HostProcessOrchestrator`) and delegates owner/membership/identity
+ * operations to it over the loopback admin channel using
+ * {@link OwnerNodeClient}. See `docs/cadre-host.md` § Control-plane
+ * separation.
+ */
+
+export { OwnerNodeClient, OwnerNodeUnavailableError } from './owner-node-client.js';
+export type { OwnerNodeClientOptions } from './owner-node-client.js';