@serfab/cadre-host 0.8.1 → 0.10.0

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/node-identity.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-node identity keys for orchestrator-managed children.
+ *
+ * A donated node joins a *foreign* cadre: the requester approves its peer id
+ * and its seed nominates dial addresses keyed to that peer id. Both bind to the
+ * identity, so a node that generated a fresh libp2p keypair per process would
+ * become a stranger to the cadre that admitted it on every restart. It also
+ * needs a stable on-disk home for its node-local stores — `cadre-cli start`
+ * opens `FileBootstrapPeerStore` / `FileTrustedOwnerStore` only when a protobuf
+ * identity key file is configured.
+ *
+ * So every managed node gets its own `identity.key` inside its workdir, written
+ * once and reused thereafter. The workdir is removed when the loan is
+ * terminated (`removeContainer`), so nothing the node persisted outlives it.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { generateIdentity, loadIdentity, type IdentityRecord } from '../installer/identity.js';
+
+const IDENTITY_FILE = 'identity.key';
+
+/** Path to a managed node's own protobuf identity key inside its workdir. */
+export function nodeIdentityPath(workdir: string): string {
+  return join(workdir, IDENTITY_FILE);
+}
+
+/**
+ * Ensure `<workdir>/identity.key` exists, generating an Ed25519 protobuf key on
+ * first call and REUSING it on every later call. Reuse is the load-bearing
+ * property: a re-spawn of the same container must land on the same peer id.
+ */
+export async function ensureNodeIdentity(workdir: string): Promise<{ path: string; peerId: string }> {
+  const path = nodeIdentityPath(workdir);
+  const record: IdentityRecord = existsSync(path)
+    ? loadIdentity(path)
+    : await generateIdentity(path);
+  return { path, peerId: record.peerId };
+}

package/src/orchestrator/port-allocator.ts

@@ -1,3 +1,5 @@
+import type { NodePorts } from './types.js';
+
 /**
  * Range-based port tracker. Allocations are in-memory; on orchestrator
  * restart the caller rehydrates the used-set from persisted state via
@@ -41,3 +43,49 @@ export class PortAllocator {
     return this.usedPorts.has(port);
   }
 }
+
+/**
+ * Allocation order for a node's port set. Fixed so that swapping a caller onto
+ * {@link allocateNodePorts} does not shift the ports an existing deployment
+ * already handed out.
+ */
+const NODE_PORT_KEYS = ['health', 'metrics', 'p2p', 'admin'] as const;
+
+/**
+ * Allocate a full NodePorts set atomically — a mid-way failure (an exhausted
+ * range) releases everything already taken rather than stranding the ports it
+ * got before the throw. `overrides` supply a port instead of allocating one
+ * (the owner node's p2p port, which is fixed by NAT config).
+ *
+ * Overrides are reserved FIRST, before any allocation, so an override that
+ * happens to sit inside the managed range cannot also be handed out to another
+ * key. Reserving is `markUsed`, a documented no-op outside the range — which is
+ * the production case for the owner node's libp2p port, and why reserving first
+ * leaves every real port assignment unchanged.
+ */
+export function allocateNodePorts(
+  allocator: PortAllocator,
+  overrides?: Partial<NodePorts>,
+): NodePorts {
+  const reserved: number[] = [];
+  const ports: Partial<NodePorts> = {};
+  try {
+    for (const key of NODE_PORT_KEYS) {
+      const override = overrides?.[key];
+      if (override === undefined) continue;
+      allocator.markUsed(override);
+      reserved.push(override);
+      ports[key] = override;
+    }
+    for (const key of NODE_PORT_KEYS) {
+      if (ports[key] !== undefined) continue;
+      const port = allocator.allocate();
+      reserved.push(port);
+      ports[key] = port;
+    }
+  } catch (err) {
+    for (const port of reserved) allocator.release(port);
+    throw err;
+  }
+  return ports as NodePorts;
+}

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';

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

@@ -1,69 +1,73 @@
 /**
- * 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
- * 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`.
+ * 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 **all three** trimmed `CadreNodeLike`
+ * interfaces — the trust-circle one (`auth/trust-circle.ts`), the NAT one
+ * (`nat/nat-service.ts`), and the strand one (`strands/strand-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';
+import type { CadreNodeLike as StrandCadreNodeLike } from '../strands/strand-service.js';
+import type { StrandListSnapshot, StrandRemovalResult } from '../strands/types.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, StrandCadreNodeLike {
   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 +127,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 +156,45 @@ export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNo
     return data.multiaddrs;
   }
 
+  // --- strand CadreNodeLike ---
+
+  /** This party's strands plus the node's current control-connection count. */
+  async listStrands(): Promise<StrandListSnapshot> {
+    return await this.request<StrandListSnapshot>('GET', '/admin/strands');
+  }
+
+  /**
+   * Remove this party's participation in one strand.
+   *
+   * `?confirm=1` is appended **only** when the caller asked for it. The node
+   * refuses an unconfirmed closed-strand removal with `confirmation_required`;
+   * that refusal is surfaced, never retried with the flag added — the row holds
+   * this party's membership key for the strand and nothing else does.
+   */
+  async removeStrand(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult> {
+    const query = opts.confirm ? '?confirm=1' : '';
+    return await this.request<StrandRemovalResult>(
+      'DELETE',
+      `/admin/strands/${encodeURIComponent(strandId)}${query}`,
+    );
+  }
+
+  // --- 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 +204,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 +227,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 +235,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');
+  });
+});