@serfab/cadre-host 0.9.0 → 0.10.0

package/src/owner/owner-node-client.ts

@@ -5,10 +5,10 @@
  * cadre-host's manager process holds no in-process `CadreNode`; it spawns the
  * 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` and `addDrone` (the
- * node-donation requester side).
+ * 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
@@ -25,6 +25,8 @@ import type { CadreInvite, DroneInitResult } from '@serfab/cadre-core';
 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:owner-client');
 
@@ -55,7 +57,8 @@ export interface OwnerNodeClientOptions {
   fetch?: typeof fetch;
 }
 
-export class OwnerNodeClient implements TrustCircleCadreNodeLike, NatCadreNodeLike {
+export class OwnerNodeClient
+implements TrustCircleCadreNodeLike, NatCadreNodeLike, StrandCadreNodeLike {
   private readonly endpointSource: EndpointSource;
   private readonly fetchImpl: typeof fetch;
 
@@ -153,6 +156,29 @@ export class OwnerNodeClient implements TrustCircleCadreNodeLike, NatCadreNodeLi
     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) ---
 
   /**

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

@@ -54,12 +54,20 @@ class FakeOrchestrator implements Orchestrator {
 let tmpRoot: string;
 let app: ReturnType<typeof Fastify>;
 let grants: GrantService;
+let store: DonationStore;
 let token: string;
+const originalFetch = globalThis.fetch;
+
+/**
+ * A well-formed 32-byte base64url owner key. `DonationService.provision`
+ * shape-checks the pins, so a placeholder string is a 400 rather than a fixture.
+ */
+const OWNER_KEY = Buffer.alloc(32, 7).toString('base64url');
 
 const body = {
   partyId: 'party-P',
   bootstrapNodes: ['/ip4/127.0.0.1/tcp/4001/p2p/12D3KooReq'],
-  ownerKeys: ['owner-key-b64url'],
+  ownerKeys: [OWNER_KEY],
 };
 
 const bearer = (t: string) => ({ authorization: `Bearer ${t}` });
@@ -68,17 +76,15 @@ 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')),
-  });
+  store = new DonationStore(join(tmpRoot, 'donations'));
+  const donations = new DonationService({ orchestrator: new FakeOrchestrator(), grants, store });
   app = Fastify();
   registerErrorHandler(app);
   registerGrantsRoutes(app, { donations, grants });
 });
 
 afterEach(async () => {
+  globalThis.fetch = originalFetch;
   await app.close();
   try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
 });
@@ -122,6 +128,32 @@ describe('POST /grants', () => {
     expect(res.statusCode).toBe(400);
   });
 
+  // A typo'd pin used to be answered 201 and only fail when the spawned child
+  // tried to decode it at boot — by which point the caller had no way to act on it.
+  it('rejects a malformed ownerKeys entry → 400 invalid_request, naming the bad key', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants', headers: bearer(token),
+      payload: { ...body, ownerKeys: [OWNER_KEY, 'this-is-not-a-key'] },
+    });
+    expect(res.statusCode).toBe(400);
+    const error = (res.json() as { error: { code: string; message: string } }).error;
+    expect(error.code).toBe('invalid_request');
+    expect(error.message).toContain('this-is-not-a-key');
+  });
+
+  // Element types are the route's job: the service's shape check assumes strings,
+  // so a number here would come back as an internal `.trim is not a function`.
+  it('rejects a non-string ownerKeys entry → 400 naming the field, not a decoder error', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants', headers: bearer(token),
+      payload: { ...body, ownerKeys: [42] },
+    });
+    expect(res.statusCode).toBe(400);
+    const error = (res.json() as { error: { code: string; message: string } }).error;
+    expect(error.code).toBe('invalid_request');
+    expect(error.message).toBe('ownerKeys must be an array of strings');
+  });
+
   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 });
@@ -173,6 +205,48 @@ describe('PUT /grants/:id/seed validation', () => {
     expect(res.statusCode).toBe(400);
     expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_request');
   });
+
+  it('answers 409 invalid_state when the loan ends while the seed is in flight', 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;
+
+    // The borrower's DELETE lands inside the seed window: the node accepts the
+    // seed, but by the time it answers the loan is over. The ending wins, so the
+    // route must NOT report a 200 that implies a live, freshly seeded node.
+    globalThis.fetch = (async () => {
+      await app.inject({ method: 'DELETE', url: `/grants/${id}`, headers: bearer(token) });
+      return { ok: true, json: async () => ({ success: true, peersAdded: 2 }) } as unknown as Response;
+    }) as typeof globalThis.fetch;
+
+    const res = await app.inject({
+      method: 'PUT', url: `/grants/${id}/seed`, headers: bearer(token), payload: { seed: 'encoded-seed' },
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_state');
+    const after = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(token) });
+    expect((after.json() as { data: { donation: { status: string } } }).data.donation.status)
+      .toBe('terminated');
+  });
+
+  it('answers 404 not_found when the record vanishes while the seed is in flight', 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;
+
+    // The row is gone by the time the node answers — the other half of the
+    // abandon mapping, which has no status to report.
+    globalThis.fetch = (async () => {
+      store.remove(id);
+      return { ok: true, json: async () => ({ success: true, peersAdded: 2 }) } as unknown as Response;
+    }) as typeof globalThis.fetch;
+
+    const res = await app.inject({
+      method: 'PUT', url: `/grants/${id}/seed`, headers: bearer(token), payload: { seed: 'encoded-seed' },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('not_found');
+  });
 });
 
 describe('DELETE /grants/:id', () => {

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

@@ -0,0 +1,233 @@
+/**
+ * `/api/strands` route tests — a real Fastify built by `createLocalUiServer`
+ * (so the error handler, the mount gate, and the static not-found fallback are
+ * all the production ones) over a fake StrandService.
+ *
+ * What the service does is covered by `strands/__tests__/strand-service.test.ts`;
+ * this file is about the HTTP contract: envelope shape, status mapping, the
+ * `confirm` query param, and exactly-once bus publication.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { createLocalUiServer } from '../index.js';
+import type { LocalUiEvent } from '../events/types.js';
+import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
+import type { StrandService } from '../../strands/index.js';
+import { StrandError } from '../../strands/index.js';
+import type { StrandListSnapshot, StrandRemovalResult } from '../../strands/index.js';
+
+function fakeOrchestrator(): HostProcessOrchestrator {
+  return {
+    listNodes: () => [],
+    getNode: () => undefined,
+    resolveDockerId: () => undefined,
+    onStateChange: () => () => undefined,
+  } as unknown as HostProcessOrchestrator;
+}
+
+const SNAPSHOT: StrandListSnapshot = {
+  strands: [
+    { id: 'open-one', type: 'o', running: true, status: 'active' },
+    { id: 'closed-one', type: 'c', running: false, status: null },
+  ],
+  controlConnections: 3,
+};
+
+interface FakeStrands {
+  service: StrandService;
+  /** Every (id, confirm) the route forwarded. */
+  calls: Array<{ strandId: string; confirm: boolean }>;
+  /** Set to make `list` and `remove` throw. */
+  failWith?: unknown;
+  /** Set to make `remove` report a strand that was never published. */
+  absent?: boolean;
+}
+
+function fakeStrandService(): FakeStrands {
+  const state: FakeStrands = {
+    calls: [],
+    service: undefined as unknown as StrandService,
+  };
+  state.service = {
+    async list(): Promise<StrandListSnapshot> {
+      if (state.failWith) throw state.failWith;
+      return SNAPSHOT;
+    },
+    async remove(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult> {
+      state.calls.push({ strandId, confirm: opts.confirm });
+      if (state.failWith) throw state.failWith;
+      return state.absent
+        ? { strandId, published: false, type: null, removed: false, alone: false }
+        : { strandId, published: true, type: 'o', removed: true, alone: false };
+    },
+  } as unknown as StrandService;
+  return state;
+}
+
+let dataDir: string;
+let server: ReturnType<typeof createLocalUiServer>;
+let strands: FakeStrands;
+let events: LocalUiEvent[];
+
+function buildServer(opts: { withStrands: boolean }): void {
+  server = createLocalUiServer({
+    uiPort: 8765,
+    dataDir,
+    orchestrator: fakeOrchestrator(),
+    ...(opts.withStrands ? { strands: strands.service } : {}),
+    forcePort: 0,
+  });
+  events = [];
+  server.events.subscribe((e) => events.push(e));
+}
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), 'cadre-host-strands-route-'));
+  strands = fakeStrandService();
+  buildServer({ withStrands: true });
+});
+
+afterEach(async () => {
+  await server.app.close();
+  rmSync(dataDir, { recursive: true, force: true });
+});
+
+describe('GET /api/strands', () => {
+  it('returns the snapshot in the /api/* envelope', async () => {
+    const res = await server.app.inject({ method: 'GET', url: '/api/strands' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { ok: boolean; data: StrandListSnapshot };
+    expect(body.ok).toBe(true);
+    expect(body.data.strands).toHaveLength(2);
+    expect(body.data.strands[0]?.id).toBe('open-one');
+    expect(body.data.controlConnections).toBe(3);
+  });
+
+  it('maps a service failure through the same error handler as the DELETE arm', async () => {
+    strands.failWith = new StrandError('node_unavailable', 'Owner node unavailable: refused');
+    const res = await server.app.inject({ method: 'GET', url: '/api/strands' });
+    expect(res.statusCode).toBe(503);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('node_unavailable');
+  });
+});
+
+describe('DELETE /api/strands/:id', () => {
+  it('removes a published strand → 200 and exactly one strands-changed event', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { ok: boolean; data: StrandRemovalResult };
+    expect(body.ok).toBe(true);
+    expect(body.data).toMatchObject({ strandId: 'open-one', published: true, removed: true });
+    expect(events).toEqual([{ type: 'strands-changed', kind: 'removed' }]);
+  });
+
+  it('an absent strand → 200, published: false, and NO event', async () => {
+    strands.absent = true;
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/never-published' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { data: StrandRemovalResult };
+    expect(body.data.published).toBe(false);
+    expect(body.data.removed).toBe(false);
+    expect(events).toEqual([]);
+  });
+
+  it('forwards confirm=1 as true and its absence as false', async () => {
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/a' });
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/b?confirm=1' });
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/c?confirm=true' });
+    expect(strands.calls).toEqual([
+      { strandId: 'a', confirm: false },
+      { strandId: 'b', confirm: true },
+      { strandId: 'c', confirm: true },
+    ]);
+  });
+
+  it('treats a guessy confirm value as NOT confirmed', async () => {
+    // `yes`/`on`/empty are refused deliberately — a typo must not destroy a
+    // closed strand's membership key.
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/a?confirm=yes' });
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/b?confirm=' });
+    expect(strands.calls).toEqual([
+      { strandId: 'a', confirm: false },
+      { strandId: 'b', confirm: false },
+    ]);
+  });
+
+  it('ignores query params other than confirm rather than proxying them', async () => {
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/a?force=1&confirm=1' });
+    expect(strands.calls).toEqual([{ strandId: 'a', confirm: true }]);
+  });
+
+  // The route is one path segment, so an id holding a `/` has to arrive
+  // percent-encoded. Fastify decodes `params`, so the service sees the literal id
+  // and forwards it — nothing in this chain needs to refuse such an id.
+  it('carries a percent-encoded "/" through to the service as a literal', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/ns%2Fstrand' });
+    expect(res.statusCode).toBe(200);
+    expect(strands.calls).toEqual([{ strandId: 'ns/strand', confirm: false }]);
+  });
+
+  it('404s an UNencoded "/" at the router, before any handler runs', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/ns/strand' });
+    expect(res.statusCode).toBe(404);
+    expect(strands.calls).toEqual([]);
+  });
+});
+
+describe('DELETE /api/strands/:id — error mapping', () => {
+  it('confirmation_required → 428 with the node message intact', async () => {
+    const message = 'Refusing to remove closed strand closed-one without confirmation: …';
+    strands.failWith = new StrandError('confirmation_required', message);
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/closed-one' });
+    expect(res.statusCode).toBe(428);
+    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe('confirmation_required');
+    expect(body.error.message).toBe(message);
+    expect(events).toEqual([]);
+  });
+
+  it('node_unavailable → 503', async () => {
+    strands.failWith = new StrandError('node_unavailable', 'Owner node unavailable: refused');
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(503);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('node_unavailable');
+  });
+
+  it('invalid_id → 400', async () => {
+    strands.failWith = new StrandError('invalid_id', 'A strand id is required');
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/%20' });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_id');
+  });
+
+  it('internal → 500', async () => {
+    strands.failWith = new StrandError('internal', 'node said something new');
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(500);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('internal');
+  });
+});
+
+describe('donor-only mode (no strands option)', () => {
+  beforeEach(async () => {
+    await server.app.close();
+    buildServer({ withStrands: false });
+  });
+
+  it('404s GET /api/strands through the static not-found handler', async () => {
+    const res = await server.app.inject({ method: 'GET', url: '/api/strands' });
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('not_found');
+  });
+
+  it('404s DELETE /api/strands/:id', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(404);
+  });
+});

package/src/server/error-handler.ts

@@ -2,7 +2,8 @@
  * Fastify error handler — translates known typed errors to stable HTTP status
  * codes and uniform `{ ok: false, error: { code, message } }` payloads.
  *
- * Codes (cross-referenced with `auth/types.ts`, `nat/types.ts`, `update/types.ts`):
+ * Codes (cross-referenced with `auth/types.ts`, `nat/types.ts`, `strands/types.ts`,
+ * `update/types.ts`):
  *   - TrustCircleError
  *       invalid_label, invalid_token             → 400
  *       not_found, already_redeemed              → 404
@@ -16,6 +17,11 @@
  *       mapping_failed, router_unreachable,
  *       ip_detection_failed, ddns_update_failed  → 500
  *       node_unavailable                         → 503
+ *   - StrandError
+ *       invalid_id                               → 400
+ *       confirmation_required                    → 428
+ *       node_unavailable                         → 503
+ *       internal                                 → 500
  *   - UpdateErrorException
  *       manifest_invalid, no_update_available,
  *       min_previous_version                     → 400
@@ -45,6 +51,7 @@ import debug from 'debug';
 
 import { TrustCircleError, type TrustCircleErrorCode } from '../auth/types.js';
 import { NatError, type NatErrorCode } from '../nat/types.js';
+import { StrandError, type StrandErrorCode } from '../strands/types.js';
 import { UpdateErrorException, type UpdateErrorCode } from '../update/types.js';
 import { GrantError, type GrantErrorCode, DonationError, type DonationErrorCode } from '../donation/types.js';
 
@@ -73,6 +80,19 @@ const NAT_STATUS: Record<NatErrorCode, number> = {
   node_unavailable: 503,
 };
 
+/**
+ * 428 (Precondition Required) for `confirmation_required`: the node refused a
+ * closed-strand removal because the caller had not confirmed. It is not a 400
+ * (the request was well-formed) and not a 409 (nothing conflicts) — the caller
+ * must re-send with the precondition satisfied.
+ */
+const STRAND_STATUS: Record<StrandErrorCode, number> = {
+  invalid_id: 400,
+  confirmation_required: 428,
+  node_unavailable: 503,
+  internal: 500,
+};
+
 const GRANT_STATUS: Record<GrantErrorCode, number> = {
   invalid_label: 400,
   invalid_max_nodes: 400,
@@ -134,6 +154,9 @@ function classify(err: FastifyError): Classified {
   if (err instanceof NatError) {
     return { status: NAT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
   }
+  if (err instanceof StrandError) {
+    return { status: STRAND_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
   if (err instanceof UpdateErrorException) {
     return { status: UPDATE_STATUS[err.code] ?? 500, code: err.code, message: err.message };
   }

package/src/server/events/types.ts

@@ -12,6 +12,7 @@ import type { DirectReachability, PortForwardMode } from '../../nat/index.js';
 export type LocalUiEvent =
   | { type: 'node-state-changed'; nodeId: string; status: ContainerStatus }
   | { type: 'trust-circle-changed'; kind: 'invited' | 'redeemed' | 'revoked' }
+  | { type: 'strands-changed'; kind: 'removed' }
   | {
       type: 'connectivity-changed';
       portMode: PortForwardMode;

package/src/server/index.ts

@@ -20,6 +20,8 @@ import type { TrustCircleService } from '../auth/index.js';
 import { createTrustCircleHandlers } from '../auth/index.js';
 import type { NatService } from '../nat/index.js';
 import { createNatHandlers } from '../nat/index.js';
+import type { StrandService } from '../strands/index.js';
+import { createStrandHandlers } from '../strands/index.js';
 import type { UpdateService } from '../update/index.js';
 import { createUpdateHandlers } from '../update/index.js';
 import type { GrantService, DonationService } from '../donation/index.js';
@@ -33,6 +35,7 @@ import { registerStaticMount } from './static.js';
 import { buildFastify, startListening, stopListening } from './server.js';
 import { registerNatRoutes } from './routes/nat.js';
 import { registerTrustCircleRoutes } from './routes/trust-circle.js';
+import { registerStrandRoutes } from './routes/strands.js';
 import { registerUpdateRoutes } from './routes/update.js';
 import { registerStatusRoute } from './routes/status.js';
 import { registerNodesRoutes } from './routes/nodes.js';
@@ -60,6 +63,12 @@ export interface LocalUiServerOptions {
    * unmounted and 404s.
    */
   nat?: NatService;
+  /**
+   * Strand service — present only when the host runs its own personal cadre.
+   * Absent in donor-only mode, where there is no owner node to ask, so
+   * `/api/strands` stays unmounted and 404s through the static handler.
+   */
+  strands?: StrandService;
   /** Optional — 6.4.2 lands this; nullable while still iterating. */
   update?: UpdateService;
   /**
@@ -133,15 +142,19 @@ export function createLocalUiServer(opts: LocalUiServerOptions): LocalUiServer {
   registerNodesRoutes(app, { orchestrator: opts.orchestrator });
   registerSettingsRoutes(app, { settingsStore, ...(opts.nat ? { nat: opts.nat } : {}), ...(opts.update ? { update: opts.update } : {}) });
 
-  // 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).
+  // Trust-circle + NAT + strand surfaces exist only when the host runs its own
+  // personal cadre. In donor-only mode they're left unmounted, so `/auth/*`,
+  // `/nat/*` and `/api/strands` 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.strands) {
+    registerStrandRoutes(app, { handlers: createStrandHandlers(opts.strands), events });
+  }
   if (opts.update) {
     registerUpdateRoutes(app, { handlers: createUpdateHandlers(opts.update), events });
   }

package/src/server/routes/grants.ts

@@ -119,6 +119,12 @@ export function registerGrantsRoutes(app: FastifyInstance, opts: GrantsRoutesOpt
     if (!Array.isArray(body.ownerKeys) || body.ownerKeys.length === 0) {
       return errorResponse(reply, 'invalid_request', 'ownerKeys is required', 400);
     }
+    // Element types too, not just the array: `provision`'s shape check trims each
+    // entry, so a non-string reaches the caller as an internal `.trim is not a
+    // function` rather than as a message naming what is wrong with the request.
+    if (!body.ownerKeys.every(key => typeof key === 'string')) {
+      return errorResponse(reply, 'invalid_request', 'ownerKeys must be an array of strings', 400);
+    }
     if (body.profile !== undefined && body.profile !== 'storage' && body.profile !== 'transaction') {
       return errorResponse(reply, 'invalid_request', 'profile must be "storage" or "transaction"', 400);
     }
@@ -169,10 +175,28 @@ export function registerGrantsRoutes(app: FastifyInstance, opts: GrantsRoutesOpt
       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);
+    // NOTE: exhaustive over today's three outcomes, and nothing forces it to stay
+    // that way — an unhandled fourth would fall out of the handler as `undefined`
+    // and hang the request rather than fail to compile. If `DonationSeedResult`
+    // ever grows a variant, add a `default:` that 500s here.
+    switch (result.outcome) {
+      case 'rejected':
+        return errorResponse(reply, 'seed_failed', result.error ?? 'Node rejected the seed', 502);
+      // The loan ended while the seed was in flight. The ending won, so the
+      // caller is told the record it seeded is no longer seedable (409) — or is
+      // gone entirely (404) — rather than a 200 that implies a live node.
+      case 'abandoned':
+        return result.status
+          ? errorResponse(
+              reply,
+              'invalid_state',
+              `Donation ${request.params.id} ended (${result.status}) while the seed was in flight`,
+              409,
+            )
+          : errorResponse(reply, 'not_found', `No such donation: ${request.params.id}`, 404);
+      case 'seeded':
+        return reply.send({ ok: true, data: { peersAdded: result.peersAdded } });
     }
-    return reply.send({ ok: true, data: { peersAdded: result.peersAdded ?? 0 } });
   });
 
   // DELETE /grants/:id — terminate the donated node.

package/src/server/routes/strands.ts

@@ -0,0 +1,54 @@
+/**
+ * Strand HTTP routes — thin adapters around `StrandHandlers`
+ * (`createStrandHandlers(service)`).
+ *
+ * Mount path: `/api/strands` — a UI-only surface with no CLI contract to
+ * preserve. (The `/auth/*` and `/nat/*` mounts sit outside `/api` only because
+ * the existing CLI already targets those URLs.) Envelope form therefore follows
+ * the other `/api/*` routes: `{ ok: true, data }`.
+ *
+ * A removal that actually issued a delete publishes `strands-changed` so other
+ * open tabs refresh. A call that found no row publishes nothing — nothing changed.
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { StrandHandlers } from '../../strands/types.js';
+import type { EventBus } from '../events/bus.js';
+
+export interface StrandRoutesOptions {
+  handlers: StrandHandlers;
+  events: EventBus;
+}
+
+/**
+ * The only accepted `confirm` values — the same strict pair the admin channel
+ * accepts. Not a general truthiness parser: `yes`, `on` and an empty value all
+ * count as NOT confirmed, because a guessy parser here would turn a typo into a
+ * destroyed membership key.
+ *
+ * NOTE: deliberately duplicated from cadre-cli's `admin-server.ts` rather than
+ * imported — cadre-host depends on cadre-cli for its bin path only, never its
+ * source. Keep the two in step by hand; do not DRY them into an import.
+ */
+const CONFIRM_VALUES = new Set(['1', 'true']);
+
+export function registerStrandRoutes(app: FastifyInstance, opts: StrandRoutesOptions): void {
+  const { handlers, events } = opts;
+
+  app.get('/api/strands', async () => {
+    return { ok: true, data: await handlers.listStrands() };
+  });
+
+  app.delete<{ Params: { id: string }; Querystring: { confirm?: string } }>(
+    '/api/strands/:id',
+    async (request) => {
+      const confirm = typeof request.query.confirm === 'string' && CONFIRM_VALUES.has(request.query.confirm);
+      const result = await handlers.removeStrand(request.params.id, { confirm });
+      if (result.removed) {
+        events.publish({ type: 'strands-changed', kind: 'removed' });
+      }
+      return { ok: true, data: result };
+    },
+  );
+}