@serfab/cadre-host 0.8.1 → 0.10.0

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

@@ -0,0 +1,263 @@
+/**
+ * Grantee-facing `/grants` route tests — the bearer-gated provisioning surface.
+ *
+ * Uses a fake orchestrator (no real children) so the focus is the HTTP contract:
+ * bearer auth, request validation, per-grant ownership isolation, the quota gate,
+ * and seedToken redaction. The live-node round-trips (peer/seed) are covered by
+ * the cross-package integration scenario.
+ */
+
+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 type {
+  Orchestrator,
+  OrchestratorCreateRequest,
+  OrchestratorCreateResult,
+  OrchestratorStats,
+} from '@serfab/cadre-provider';
+
+import { registerErrorHandler } from '../error-handler.js';
+import { registerGrantsRoutes } from '../routes/grants.js';
+import { DonationService } from '../../donation/donation-service.js';
+import { DonationStore } from '../../donation/donation-store.js';
+import { GrantService } from '../../donation/grant-service.js';
+import { GrantStore } from '../../donation/grant-store.js';
+
+class FakeOrchestrator implements Orchestrator {
+  stopped: string[] = [];
+  removed: string[] = [];
+  private counter = 0;
+  async createContainer(_request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
+    const n = ++this.counter;
+    return {
+      dockerId: `dock_${n}`,
+      healthEndpoint: `http://127.0.0.1:${9000 + n}/health`,
+      metricsEndpoint: `http://127.0.0.1:${9000 + n}/metrics`,
+      seedEndpoint: `http://127.0.0.1:${9000 + n}/seed`,
+      seedToken: `seed-token-${n}`,
+      p2pPort: 4000 + n,
+    };
+  }
+  async stopContainer(id: string): Promise<void> { this.stopped.push(id); }
+  async removeContainer(id: string): Promise<void> { this.removed.push(id); }
+  async getStats(): Promise<OrchestratorStats> {
+    return { cpuPercent: 0, memoryBytes: 0, networkRxBytes: 0, networkTxBytes: 0 };
+  }
+  async isRunning(): Promise<boolean> { return true; }
+  async getLogs(): Promise<string> { return ''; }
+}
+
+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],
+};
+
+const bearer = (t: string) => ({ authorization: `Bearer ${t}` });
+
+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;
+  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 */ }
+});
+
+describe('POST /grants', () => {
+  it('provisions a donated node → 201, awaiting_seed, seedToken redacted', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    expect(res.statusCode).toBe(201);
+    const donation = (res.json() as { data: { donation: Record<string, unknown> } }).data.donation;
+    expect(donation.status).toBe('awaiting_seed');
+    expect(donation.partyId).toBe('party-P');
+    expect(donation.seedToken).toBeUndefined();
+    expect(donation.seedEndpoint).toBeUndefined();
+  });
+
+  it('rejects a missing bearer → 401', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', payload: body });
+    expect(res.statusCode).toBe(401);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('unauthorized');
+  });
+
+  it('rejects an unknown bearer → 401', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', headers: bearer('nope'), payload: body });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a missing partyId → 400 invalid_request', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants', headers: bearer(token),
+      payload: { bootstrapNodes: body.bootstrapNodes, ownerKeys: body.ownerKeys },
+    });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_request');
+  });
+
+  it('rejects empty ownerKeys → 400 invalid_request', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants', headers: bearer(token),
+      payload: { ...body, ownerKeys: [] },
+    });
+    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 });
+    expect(first.statusCode).toBe(201);
+    const second = await app.inject({ method: 'POST', url: '/grants', headers: bearer(g), payload: body });
+    expect(second.statusCode).toBe(429);
+    expect((second.json() as { error: { code: string } }).error.code).toBe('quota_exceeded');
+  });
+});
+
+describe('GET /grants auth', () => {
+  it('rejects an unknown bearer → 401 unauthorized (code matches the status)', async () => {
+    const res = await app.inject({ method: 'GET', url: '/grants', headers: bearer('nope') });
+    expect(res.statusCode).toBe(401);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('unauthorized');
+  });
+});
+
+describe('GET /grants (ownership isolation)', () => {
+  it('lists only the donations the presented grant authorized', async () => {
+    const other = grants.issue({ label: 'Carol' }).token;
+    await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    await app.inject({ method: 'POST', url: '/grants', headers: bearer(other), payload: body });
+
+    const mine = await app.inject({ method: 'GET', url: '/grants', headers: bearer(token) });
+    const donations = (mine.json() as { data: { donations: Array<{ grantToken: string }> } }).data.donations;
+    expect(donations).toHaveLength(1);
+    expect(donations[0].grantToken).toBe(token);
+  });
+
+  it('a foreign grant cannot read another grant’s donation → 404', async () => {
+    const other = grants.issue({ label: 'Carol' }).token;
+    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;
+
+    const mine = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(token) });
+    expect(mine.statusCode).toBe(200);
+
+    const foreign = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(other) });
+    expect(foreign.statusCode).toBe(404);
+  });
+});
+
+describe('PUT /grants/:id/seed validation', () => {
+  it('rejects a missing seed body → 400 invalid_request', 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;
+    const res = await app.inject({ method: 'PUT', url: `/grants/${id}/seed`, headers: bearer(token), payload: {} });
+    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', () => {
+  it('terminates a donation and drops it from the live tally', 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;
+
+    const del = await app.inject({ method: 'DELETE', url: `/grants/${id}`, headers: bearer(token) });
+    expect(del.statusCode).toBe(200);
+
+    const one = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(token) });
+    expect((one.json() as { data: { donation: { status: string } } }).data.donation.status).toBe('terminated');
+  });
+});

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

@@ -21,7 +21,7 @@ interface FakeOrchestrator extends HostProcessOrchestrator {
 
 function fakeOrchestrator(
   initial: ManagedNodeInfo[] = [],
-  opts: { authorityId?: string; hasAuthorityConfig?: boolean } = {},
+  opts: { ownerId?: string; hasOwnerConfig?: boolean } = {},
 ): FakeOrchestrator {
   const nodes = new Map(initial.map((n) => [n.dockerId, n]));
   const listeners = new Set<NodeStateListener>();
@@ -41,21 +41,21 @@ function fakeOrchestrator(
       for (const n of nodes.values()) if (n.id === id) return n.dockerId;
       return undefined;
     },
-    isAuthorityNode: (id: string) => {
-      if (!opts.authorityId) return false;
+    isOwnerNode: (id: string) => {
+      if (!opts.ownerId) return false;
       const node = findById(id);
-      return id === opts.authorityId || node?.id === opts.authorityId;
+      return id === opts.ownerId || node?.id === opts.ownerId;
     },
-    hasAuthorityConfig: () => opts.hasAuthorityConfig ?? false,
-    ensureAuthorityNode: async () => {
+    hasOwnerConfig: () => opts.hasOwnerConfig ?? false,
+    ensureOwnerNode: async () => {
       counters.ensured++;
-      const node = opts.authorityId ? findById(opts.authorityId) : undefined;
-      return node ?? { id: opts.authorityId, status: 'running' } as unknown as ManagedNodeInfo;
+      const node = opts.ownerId ? findById(opts.ownerId) : undefined;
+      return node ?? { id: opts.ownerId, status: 'running' } as unknown as ManagedNodeInfo;
     },
-    restartAuthorityNode: async () => {
+    restartOwnerNode: async () => {
       counters.restarted++;
-      const node = opts.authorityId ? findById(opts.authorityId) : undefined;
-      return node ?? { id: opts.authorityId, status: 'running' } as unknown as ManagedNodeInfo;
+      const node = opts.ownerId ? findById(opts.ownerId) : undefined;
+      return node ?? { id: opts.ownerId, status: 'running' } as unknown as ManagedNodeInfo;
     },
     onStateChange: (l: NodeStateListener) => { listeners.add(l); return () => { listeners.delete(l); }; },
     stopContainer: async (dockerId: string) => {
@@ -171,14 +171,14 @@ describe('/api/nodes routes', () => {
     ]);
   });
 
-  it('POST /api/nodes/:id/start on a non-authority node returns 501 not_implemented', async () => {
+  it('POST /api/nodes/:id/start on a non-owner node returns 501 not_implemented', async () => {
     const res = await app.inject({ method: 'POST', url: '/api/nodes/alice/start' });
     expect(res.statusCode).toBe(501);
     const body = res.json() as { error: { code: string } };
     expect(body.error.code).toBe('not_implemented');
   });
 
-  it('POST /api/nodes/:id/restart on a non-authority node returns 501 not_implemented', async () => {
+  it('POST /api/nodes/:id/restart on a non-owner node returns 501 not_implemented', async () => {
     const res = await app.inject({ method: 'POST', url: '/api/nodes/alice/restart' });
     expect(res.statusCode).toBe(501);
   });
@@ -191,9 +191,9 @@ describe('/api/nodes routes', () => {
   });
 });
 
-describe('/api/nodes — authority node start/restart', () => {
-  const AUTHORITY_NODE: ManagedNodeInfo = {
-    id: 'authority',
+describe('/api/nodes — owner node start/restart', () => {
+  const OWNER_NODE: ManagedNodeInfo = {
+    id: 'owner',
     dockerId: '999:tok',
     partyId: 'install-id',
     profile: 'storage',
@@ -201,7 +201,7 @@ describe('/api/nodes — authority node start/restart', () => {
     spawnedAt: '2025-01-01T00:00:00Z',
     workdir: '',
     ports: { health: 1, metrics: 2, p2p: 4555, admin: 3 },
-    authority: true,
+    owner: true,
   };
 
   let app: ReturnType<typeof Fastify>;
@@ -210,30 +210,30 @@ describe('/api/nodes — authority node start/restart', () => {
   beforeEach(() => {
     app = Fastify();
     registerErrorHandler(app);
-    orchestrator = fakeOrchestrator([AUTHORITY_NODE], { authorityId: 'authority', hasAuthorityConfig: true });
+    orchestrator = fakeOrchestrator([OWNER_NODE], { ownerId: 'owner', hasOwnerConfig: true });
     registerNodesRoutes(app, { orchestrator });
   });
 
   afterEach(async () => { await app.close(); });
 
-  it('start ensures the authority node', async () => {
-    const res = await app.inject({ method: 'POST', url: '/api/nodes/authority/start' });
+  it('start ensures the owner node', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/owner/start' });
     expect(res.statusCode).toBe(200);
     expect(orchestrator.__ensured).toBe(1);
   });
 
-  it('restart re-spawns the authority node', async () => {
-    const res = await app.inject({ method: 'POST', url: '/api/nodes/authority/restart' });
+  it('restart re-spawns the owner node', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/nodes/owner/restart' });
     expect(res.statusCode).toBe(200);
     expect(orchestrator.__restarted).toBe(1);
   });
 
-  it('start returns 501 when there is no saved authority config', async () => {
+  it('start returns 501 when there is no saved owner config', async () => {
     const app2 = Fastify();
     registerErrorHandler(app2);
-    const orch2 = fakeOrchestrator([AUTHORITY_NODE], { authorityId: 'authority', hasAuthorityConfig: false });
+    const orch2 = fakeOrchestrator([OWNER_NODE], { ownerId: 'owner', hasOwnerConfig: false });
     registerNodesRoutes(app2, { orchestrator: orch2 });
-    const res = await app2.inject({ method: 'POST', url: '/api/nodes/authority/start' });
+    const res = await app2.inject({ method: 'POST', url: '/api/nodes/owner/start' });
     expect(res.statusCode).toBe(501);
     await app2.close();
   });

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__/status-route.test.ts

@@ -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);