@serfab/cadre-host 0.7.1 → 0.9.0

package/src/server/__tests__/server.smoke.test.ts

@@ -9,6 +9,7 @@ import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
 import type { TrustCircleService } from '../../auth/index.js';
 import type { NatService } from '../../nat/index.js';
 import type { NatStatusSnapshot } from '../../nat/types.js';
+import { GrantService, GrantStore } from '../../donation/index.js';
 
 function fakeOrchestrator(): HostProcessOrchestrator {
   return {
@@ -176,3 +177,77 @@ describe('createLocalUiServer smoke', () => {
     expect(body.error.code).toBe('not_found');
   });
 });
+
+// Donor-only mode: the common case (ownCadre.enabled=false). No owner node, so
+// no trustCircle / NAT are wired. The donor surface (/grants-admin) is up, and
+// the founder-only surfaces (/auth, /nat) 404 to keep the surface honest.
+describe('createLocalUiServer smoke — donor-only (no owner node)', () => {
+  let dataDir: string;
+  let server: ReturnType<typeof createLocalUiServer>;
+  let baseUrl: string;
+
+  beforeEach(async () => {
+    dataDir = mkdtempSync(join(tmpdir(), 'cadre-host-donor-'));
+    writeConfig(dataDir);
+    server = createLocalUiServer({
+      uiPort: 8765,
+      dataDir,
+      orchestrator: fakeOrchestrator(),
+      grants: new GrantService({ store: new GrantStore(dataDir) }),
+      forcePort: 0,
+    });
+    const { url } = await server.start();
+    baseUrl = url;
+  });
+
+  afterEach(async () => {
+    await server.stop();
+    rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('serves /api/status with no trustCircle / connectivity and no nodes', async () => {
+    const res = await fetch(`${baseUrl}/api/status`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as {
+      service: { name: string };
+      nodes: unknown[];
+      trustCircle?: unknown;
+      connectivity?: unknown;
+    };
+    expect(body.service.name).toBe('cadre-host');
+    expect(body.nodes).toEqual([]);
+    expect(body.trustCircle).toBeUndefined();
+    expect(body.connectivity).toBeUndefined();
+  });
+
+  it('serves the donor surface: POST /grants-admin issues a grant', async () => {
+    const res = await fetch(`${baseUrl}/grants-admin`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ label: "Alice's cadre", maxNodes: 2 }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json() as { grant: { token: string; maxNodes: number } };
+    expect(body.grant.token).toBeTruthy();
+    expect(body.grant.maxNodes).toBe(2);
+  });
+
+  it('404s the founder-only NAT surface (GET /nat/status)', async () => {
+    const res = await fetch(`${baseUrl}/nat/status`);
+    expect(res.status).toBe(404);
+    const body = await res.json() as { error: { code: string } };
+    expect(body.error.code).toBe('not_found');
+  });
+
+  it('404s the founder-only trust-circle surface (/auth/*)', async () => {
+    const list = await fetch(`${baseUrl}/auth/trust-circle`);
+    expect(list.status).toBe(404);
+
+    const invite = await fetch(`${baseUrl}/auth/invites`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ label: 'Mom' }),
+    });
+    expect(invite.status).toBe(404);
+  });
+});

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

@@ -149,6 +149,23 @@ describe('/api/settings routes', () => {
     expect(body.error.message).toMatch(/uiPort/);
   });
 
+  it('PUT ownCadre returns 400 invalid_setting (install-time only)', async () => {
+    writeV2Config(dataDir);
+    app = Fastify();
+    registerErrorHandler(app);
+    registerSettingsRoutes(app, { settingsStore: new HostSettingsStore({ dataDir }), nat: fakeNat().svc });
+    const res = await app.inject({
+      method: 'PUT',
+      url: '/api/settings',
+      headers: { 'content-type': 'application/json' },
+      payload: JSON.stringify({ ownCadre: { enabled: true } }),
+    });
+    expect(res.statusCode).toBe(400);
+    const body = res.json() as { error: { code: string; message: string } };
+    expect(body.error.code).toBe('invalid_setting');
+    expect(body.error.message).toMatch(/ownCadre/);
+  });
+
   it('PUT unknown setting returns 400', async () => {
     writeV2Config(dataDir);
     app = Fastify();

package/src/server/__tests__/static.test.ts

@@ -0,0 +1,145 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, normalize, relative, sep } from 'node:path';
+
+import Fastify from 'fastify';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { registerStaticMount, resolveSafe } from '../static.js';
+
+describe('resolveSafe', () => {
+  // POSIX-style fixtures; node:path normalizes separators per-platform, so the
+  // containment logic is exercised identically on Windows and POSIX.
+  const root = '/srv/app/dist/ui';
+
+  it('resolves a normal in-root asset', () => {
+    expect(resolveSafe(root, '/assets/app.js')).toBe(normalize(join(root, 'assets/app.js')));
+  });
+
+  it('resolves a bare / to the root directory itself', () => {
+    expect(resolveSafe(root, '/')).toBe(normalize(root));
+  });
+
+  it('resolves /index.html to the root index', () => {
+    expect(resolveSafe(root, '/index.html')).toBe(normalize(join(root, 'index.html')));
+  });
+
+  it('rejects the sibling-directory prefix bypass', () => {
+    // `ui-private` shares `ui`'s basename as a prefix — the bare startsWith
+    // guard accepted this; the relative-based guard must reject it.
+    expect(resolveSafe(root, '/../ui-private/secret')).toBeNull();
+  });
+
+  it('accepts an in-root asset whose name merely begins with ".."', () => {
+    // `..foo` is a legitimate descendant — the containment guard must not reject
+    // it via a loose '..' prefix match (the precise check keys on '..' + sep).
+    expect(resolveSafe(root, '/..foo.js')).toBe(normalize(join(root, '..foo.js')));
+  });
+
+  it('rejects ordinary out-of-tree traversal', () => {
+    expect(resolveSafe(root, '/../../etc/passwd')).toBeNull();
+  });
+
+  it('rejects an encoded out-of-tree traversal', () => {
+    expect(resolveSafe(root, '/%2e%2e/%2e%2e/etc/passwd')).toBeNull();
+  });
+
+  it('rejects a NUL-byte path', () => {
+    expect(resolveSafe(root, '/app%00.js')).toBeNull();
+  });
+
+  it('rejects malformed percent-encoding', () => {
+    expect(resolveSafe(root, '/%')).toBeNull();
+  });
+
+  it('never returns a path that escapes the root', () => {
+    const escapes = [
+      '/../ui-private/secret',
+      '/../../etc/passwd',
+      '/../ui/../ui-private/x',
+      '/..',
+    ];
+    for (const p of escapes) {
+      const resolved = resolveSafe(root, p);
+      if (resolved !== null) {
+        const rel = relative(normalize(root), resolved);
+        expect(rel === '..' || rel.startsWith('..' + sep)).toBe(false);
+      }
+    }
+  });
+});
+
+describe('serveStatic (via registerStaticMount)', () => {
+  let app: ReturnType<typeof Fastify>;
+  let tmpRoot: string;
+  let rootDir: string;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-static-'));
+    rootDir = join(tmpRoot, 'ui');
+    mkdirSync(join(rootDir, 'assets'), { recursive: true });
+    writeFileSync(join(rootDir, 'index.html'), '<!doctype html><title>spa</title>');
+    writeFileSync(join(rootDir, 'assets', 'app.js'), 'console.log("hi");');
+
+    // Sibling directory whose name is a prefix superset of the root basename.
+    const sibling = join(tmpRoot, 'ui-private');
+    mkdirSync(sibling, { recursive: true });
+    writeFileSync(join(sibling, 'secret.txt'), 'top secret');
+
+    app = Fastify();
+    registerStaticMount(app, { rootDir });
+  });
+
+  afterEach(async () => {
+    await app.close();
+    try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it('serves an in-root asset', async () => {
+    const res = await app.inject({ method: 'GET', url: '/assets/app.js' });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toContain('application/javascript');
+    expect(res.body).toBe('console.log("hi");');
+  });
+
+  it('serves index.html for the bare root', async () => {
+    const res = await app.inject({ method: 'GET', url: '/' });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toContain('text/html');
+    expect(res.body).toContain('<title>spa</title>');
+  });
+
+  it('serves index.html as SPA fallback for unknown HTML routes', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/some/client/route',
+      headers: { accept: 'text/html' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toContain('<title>spa</title>');
+  });
+
+  // HTTP-level regression for the sibling-prefix bypass. Two vector classes:
+  //   - literal / `%2e%2e`-with-literal-slash: Fastify's router collapses the
+  //     `../` to a within-root path before the handler, so these never reach
+  //     `resolveSafe` in escaping form — they pass regardless of the fix.
+  //   - encoded-SEPARATOR (`%2f`/`%5c`): Fastify does NOT collapse these; the
+  //     handler sees the still-encoded url, `decodeSafe` then reconstitutes
+  //     `../`, and the escaping path DOES reach `resolveSafe`. Under the old
+  //     `startsWith` guard this served the sibling secret over HTTP — a genuine
+  //     exploit. These cases fail without the `relative`-based guard.
+  // Either way the asserted invariant is the same: sibling content never leaks.
+  it('never serves sibling-prefix directory content over HTTP', async () => {
+    const vectors = [
+      '/../ui-private/secret.txt',
+      '/%2e%2e/ui-private/secret.txt',
+      '/..%2fui-private%2fsecret.txt',
+      '/%2e%2e%2fui-private%2fsecret.txt',
+      '/..%5cui-private%5csecret.txt',
+    ];
+    for (const url of vectors) {
+      const res = await app.inject({ method: 'GET', url });
+      expect(res.body).not.toContain('top secret');
+    }
+  });
+});

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

@@ -1,5 +1,5 @@
 import Fastify from 'fastify';
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 
 import { registerErrorHandler } from '../error-handler.js';
 import { registerStatusRoute } from '../routes/status.js';
@@ -64,7 +64,7 @@ describe('GET /api/status', () => {
           status: 'running',
           spawnedAt: '2025-01-01T00:00:00Z',
           workdir: '/tmp/alice',
-          ports: { health: 1, metrics: 2, p2p: 3 },
+          ports: { health: 1, metrics: 2, p2p: 3, admin: 4 },
         },
       ]),
       trustCircle: fakeTrustCircle({
@@ -91,6 +91,27 @@ describe('GET /api/status', () => {
     expect(body.update).toBeUndefined();
   });
 
+  it('omits trustCircle + connectivity in donor-only mode (no trust circle / NAT wired)', async () => {
+    app = Fastify();
+    registerErrorHandler(app);
+    registerStatusRoute(app, {
+      orchestrator: fakeOrchestrator([]),
+    });
+
+    const res = await app.inject({ method: 'GET', url: '/api/status' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      service: { name: string };
+      nodes: unknown[];
+      trustCircle?: unknown;
+      connectivity?: unknown;
+    };
+    expect(body.service.name).toBe('cadre-host');
+    expect(body.nodes).toEqual([]);
+    expect(body.trustCircle).toBeUndefined();
+    expect(body.connectivity).toBeUndefined();
+  });
+
   it('includes update info when service is present', async () => {
     app = Fastify();
     registerErrorHandler(app);

package/src/server/error-handler.ts

@@ -7,6 +7,7 @@
  *       invalid_label, invalid_token             → 400
  *       not_found, already_redeemed              → 404
  *       expired                                  → 410
+ *       node_unavailable                         → 503
  *       storage_error                            → 500
  *   - NatError
  *       invalid_config, ddns_provider_unknown,
@@ -14,12 +15,28 @@
  *       secrets_unavailable, storage_error,
  *       mapping_failed, router_unreachable,
  *       ip_detection_failed, ddns_update_failed  → 500
+ *       node_unavailable                         → 503
  *   - 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")
  */
 
@@ -29,6 +46,7 @@ import debug from 'debug';
 import { TrustCircleError, type TrustCircleErrorCode } from '../auth/types.js';
 import { NatError, type NatErrorCode } from '../nat/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');
 
@@ -39,6 +57,7 @@ const TRUST_STATUS: Record<TrustCircleErrorCode, number> = {
   already_redeemed: 404,
   expired: 410,
   storage_error: 500,
+  node_unavailable: 503,
 };
 
 const NAT_STATUS: Record<NatErrorCode, number> = {
@@ -51,6 +70,28 @@ const NAT_STATUS: Record<NatErrorCode, number> = {
   router_unreachable: 500,
   ip_detection_failed: 500,
   ddns_update_failed: 500,
+  node_unavailable: 503,
+};
+
+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> = {
@@ -96,6 +137,12 @@ function classify(err: FastifyError): Classified {
   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/index.ts

@@ -22,6 +22,8 @@ import type { NatService } from '../nat/index.js';
 import { createNatHandlers } from '../nat/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';
@@ -35,6 +37,8 @@ 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 +48,33 @@ 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;
   /** 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 +126,33 @@ 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 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).
+  if (opts.trustCircle) {
+    registerTrustCircleRoutes(app, { handlers: createTrustCircleHandlers(opts.trustCircle), events });
+  }
+  if (opts.nat) {
+    registerNatRoutes(app, { handlers: createNatHandlers(opts.nat), 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 +189,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 };
+  });
+}