@serfab/cadre-host 0.8.1 → 0.10.0

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,12 +17,32 @@
  *       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
  *       apply_in_progress                        → 409
  *       signature_invalid, unsupported_state_version,
  *       apply_failed, rollback_failed, storage_error → 500
+ *   - GrantError
+ *       invalid_label, invalid_max_nodes,
+ *       invalid_ttl                              → 400
+ *       not_found                                → 404
+ *       storage_error                            → 500
+ *   - DonationError
+ *       invalid_request                          → 400
+ *       unauthorized                             → 401
+ *       forbidden                                → 403
+ *       not_found                                → 404
+ *       invalid_state                            → 409
+ *       quota_exceeded                           → 429
+ *       orchestrator_error, storage_error        → 500
+ *       seed_failed                              → 502
+ *       peer_unavailable                         → 503
  *   - everything else                            → 500 (code "internal")
  */
 
@@ -30,7 +51,9 @@ 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';
 
 const log = debug('cadre:host:error-handler');
 
@@ -57,6 +80,40 @@ 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,
+  invalid_ttl: 400,
+  not_found: 404,
+  storage_error: 500,
+};
+
+const DONATION_STATUS: Record<DonationErrorCode, number> = {
+  unauthorized: 401,
+  forbidden: 403,
+  quota_exceeded: 429,
+  invalid_request: 400,
+  not_found: 404,
+  invalid_state: 409,
+  seed_failed: 502,
+  peer_unavailable: 503,
+  orchestrator_error: 500,
+  storage_error: 500,
+};
+
 const UPDATE_STATUS: Record<UpdateErrorCode, number> = {
   manifest_invalid: 400,
   no_update_available: 400,
@@ -97,9 +154,18 @@ 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 };
   }
+  if (err instanceof GrantError) {
+    return { status: GRANT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof DonationError) {
+    return { status: DONATION_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
   // Fastify body-parsing / validation errors have a statusCode we should honour.
   if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600) {
     return {

package/src/server/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,8 +20,12 @@ 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';
+import { createGrantAdminHandlers } from '../donation/index.js';
 
 import { EventBus } from './events/bus.js';
 import { registerSseRoute } from './events/sse-route.js';
@@ -31,10 +35,13 @@ 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';
 import { registerSettingsRoutes } from './routes/settings.js';
+import { registerGrantsAdminRoutes } from './routes/grants-admin.js';
+import { registerGrantsRoutes } from './routes/grants.js';
 import { HostSettingsStore } from './settings-store.js';
 
 export interface LocalUiServerOptions {
@@ -44,10 +51,39 @@ export interface LocalUiServerOptions {
   dataDir: string;
   /** Wired dependencies — all owned by the caller. */
   orchestrator: HostProcessOrchestrator;
-  trustCircle: TrustCircleService;
-  nat: NatService;
+  /**
+   * Trust-circle service — present only when the host runs its own personal
+   * cadre (`ownCadre.enabled`). Absent in donor-only mode, where `/auth/*`
+   * stays unmounted and 404s.
+   */
+  trustCircle?: TrustCircleService;
+  /**
+   * NAT service — present only when the host runs its own personal cadre.
+   * Absent in donor-only mode (loopback-only in v1), where `/nat/*` stays
+   * unmounted and 404s.
+   */
+  nat?: NatService;
+  /**
+   * 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;
+  /**
+   * Donation grant layer. When present, mounts the loopback admin surface at
+   * `/grants-admin` (issue/list/revoke). Optional so existing callers/tests
+   * that don't exercise donations need not wire it.
+   */
+  grants?: GrantService;
+  /**
+   * Donation lifecycle service. When present (alongside `grants`), mounts the
+   * bearer-gated grantee-facing provisioning surface at `/grants`
+   * (provision / peer / seed / terminate). Optional so callers/tests that don't
+   * exercise the donor path need not wire it.
+   */
+  donations?: DonationService;
   /** Settings I/O facade. Defaults to a new one rooted at `dataDir`. */
   settingsStore?: HostSettingsStore;
   /** Bus instance — pass the same one to subsystems that publish events. */
@@ -99,18 +135,37 @@ export function createLocalUiServer(opts: LocalUiServerOptions): LocalUiServer {
 
   registerStatusRoute(app, {
     orchestrator: opts.orchestrator,
-    trustCircle: opts.trustCircle,
-    nat: opts.nat,
+    ...(opts.trustCircle ? { trustCircle: opts.trustCircle } : {}),
+    ...(opts.nat ? { nat: opts.nat } : {}),
     ...(opts.update ? { update: opts.update } : {}),
   });
   registerNodesRoutes(app, { orchestrator: opts.orchestrator });
-  registerSettingsRoutes(app, { settingsStore, nat: opts.nat, ...(opts.update ? { update: opts.update } : {}) });
+  registerSettingsRoutes(app, { settingsStore, ...(opts.nat ? { nat: opts.nat } : {}), ...(opts.update ? { update: opts.update } : {}) });
 
-  registerTrustCircleRoutes(app, { handlers: createTrustCircleHandlers(opts.trustCircle), events });
-  registerNatRoutes(app, { handlers: createNatHandlers(opts.nat), events });
+  // Trust-circle + NAT + 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 });
   }
+  if (opts.grants) {
+    registerGrantsAdminRoutes(app, { handlers: createGrantAdminHandlers(opts.grants) });
+    // Grantee-facing provisioning surface needs both the donation service and a
+    // grant validator (the GrantService doubles as the validator).
+    if (opts.donations) {
+      registerGrantsRoutes(app, { donations: opts.donations, grants: opts.grants });
+    }
+  }
 
   // Static mount registers as the not-found handler — declared last so the
   // API paths above win.
@@ -147,16 +202,19 @@ export function createLocalUiServer(opts: LocalUiServerOptions): LocalUiServer {
       );
 
       // One-shot connectivity publish — the SPA will get a sane initial
-      // signal even if no settings have changed yet this session.
-      try {
-        const snap = opts.nat.getStatus();
-        events.publish({
-          type: 'connectivity-changed',
-          portMode: snap.portMode,
-          directReachability: snap.directReachability,
-        });
-      } catch {
-        // NatService.start may not have completed; harmless to skip.
+      // signal even if no settings have changed yet this session. Skipped in
+      // donor-only mode, where there is no NatService.
+      if (opts.nat) {
+        try {
+          const snap = opts.nat.getStatus();
+          events.publish({
+            type: 'connectivity-changed',
+            portMode: snap.portMode,
+            directReachability: snap.directReachability,
+          });
+        } catch {
+          // NatService.start may not have completed; harmless to skip.
+        }
       }
 
       // Update observer: poll UpdateService.getState() every 60 s and emit

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

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