@serfab/cadre-host 0.7.1 → 0.8.1

package/src/auth/types.ts

@@ -62,6 +62,7 @@ export interface TrustCircleSnapshot {
  *   - `not_found`   → 404 (unknown token / unknown peer)
  *   - `expired`     → 410 (invite past expiresAt)
  *   - `already_redeemed` → 409 (token was used and is gone)
+ *   - `node_unavailable` → 503 (authority node admin channel down/not ready)
  *   - default       → 500
  */
 export interface TrustCircleHandlers {
@@ -82,7 +83,9 @@ export type TrustCircleErrorCode =
   | 'already_redeemed'
   | 'invalid_label'
   | 'invalid_token'
-  | 'storage_error';
+  | 'storage_error'
+  /** The authority node's admin channel is unreachable / not ready. */
+  | 'node_unavailable';
 
 /** Typed error carrying a stable `code` for HTTP mapping. */
 export class TrustCircleError extends Error {

package/src/authority/__tests__/authority-node-client.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import http from 'node:http';
+
+import { AuthorityNodeClient, AuthorityNodeUnavailableError } from '../authority-node-client.js';
+import type { AuthorityAdminEndpoint } from '../../orchestrator/index.js';
+
+/**
+ * Stub HTTP server matching the 6.6 admin contract. Records the last request
+ * so tests can assert method/path/headers/body, and lets each test choose the
+ * response.
+ */
+interface Recorded {
+  method: string;
+  path: string;
+  auth: string | undefined;
+  body: string;
+}
+
+const TOKEN = 'secret-bearer-token';
+
+let server: http.Server;
+let baseUrl: string;
+let last: Recorded | null;
+let responder: (req: Recorded) => { status: number; payload: unknown };
+
+beforeEach(async () => {
+  last = null;
+  responder = () => ({ status: 200, payload: { ok: true, data: { ok: true } } });
+  server = http.createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c) => chunks.push(c as Buffer));
+    req.on('end', () => {
+      const rec: Recorded = {
+        method: req.method ?? 'GET',
+        path: req.url ?? '/',
+        auth: req.headers['authorization'] as string | undefined,
+        body: Buffer.concat(chunks).toString('utf8'),
+      };
+      last = rec;
+      const { status, payload } = responder(rec);
+      res.writeHead(status, { 'content-type': 'application/json' });
+      res.end(JSON.stringify(payload));
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  baseUrl = `http://127.0.0.1:${port}`;
+});
+
+afterEach(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+});
+
+function makeClient(): AuthorityNodeClient {
+  const endpoint: AuthorityAdminEndpoint = { baseUrl, token: TOKEN };
+  return new AuthorityNodeClient(endpoint);
+}
+
+describe('AuthorityNodeClient', () => {
+  it('createInvite POSTs /admin/invites with bearer + body and unwraps data', async () => {
+    responder = () => ({
+      status: 200,
+      payload: { ok: true, data: { invite: { partyId: 'p', authorityAddrs: [], token: 't', createdAt: 1 }, encodedInvite: 'enc' } },
+    });
+    const client = makeClient();
+    const result = await client.createInvite('t', 60_000);
+
+    expect(result.encodedInvite).toBe('enc');
+    expect(last?.method).toBe('POST');
+    expect(last?.path).toBe('/admin/invites');
+    expect(last?.auth).toBe(`Bearer ${TOKEN}`);
+    expect(JSON.parse(last!.body)).toEqual({ token: 't', expiresInMs: 60_000 });
+  });
+
+  it('acceptPhone POSTs /admin/accept-phone', async () => {
+    const client = makeClient();
+    await client.acceptPhone({ phonePeerId: '12D3KooWX', token: 't' }, { partyId: 'p', authorityAddrs: [], token: 't', createdAt: 1 });
+    expect(last?.method).toBe('POST');
+    expect(last?.path).toBe('/admin/accept-phone');
+    const body = JSON.parse(last!.body);
+    expect(body.phonePeerId).toBe('12D3KooWX');
+    expect(body.issuedInvite.token).toBe('t');
+  });
+
+  it('removePeer DELETEs /admin/members/:peerId (url-encoded)', async () => {
+    const client = makeClient();
+    await client.removePeer('12D3KooWMember');
+    expect(last?.method).toBe('DELETE');
+    expect(last?.path).toBe('/admin/members/12D3KooWMember');
+  });
+
+  it('listMembers GETs /admin/members and returns the array', async () => {
+    responder = () => ({ status: 200, payload: { ok: true, data: { members: [{ peerId: 'a', multiaddr: '/ip4/1.2.3.4/tcp/1' }] } } });
+    const client = makeClient();
+    const members = await client.listMembers();
+    expect(last?.method).toBe('GET');
+    expect(last?.path).toBe('/admin/members');
+    expect(members).toEqual([{ peerId: 'a', multiaddr: '/ip4/1.2.3.4/tcp/1' }]);
+  });
+
+  it('isMember GETs /admin/members/:peerId and returns the boolean', async () => {
+    responder = () => ({ status: 200, payload: { ok: true, data: { member: true } } });
+    const client = makeClient();
+    expect(await client.isMember('peer-1')).toBe(true);
+    expect(last?.path).toBe('/admin/members/peer-1');
+  });
+
+  it('getPeerId GETs /admin/identity', async () => {
+    responder = () => ({ status: 200, payload: { ok: true, data: { peerId: '12D3KooWHost', partyId: 'party' } } });
+    const client = makeClient();
+    expect(await client.getPeerId()).toBe('12D3KooWHost');
+    expect(last?.path).toBe('/admin/identity');
+  });
+
+  it('getMultiaddrs GETs /admin/multiaddrs', async () => {
+    responder = () => ({ status: 200, payload: { ok: true, data: { multiaddrs: ['/ip4/0.0.0.0/tcp/4001'] } } });
+    const client = makeClient();
+    expect(await client.getMultiaddrs()).toEqual(['/ip4/0.0.0.0/tcp/4001']);
+    expect(last?.path).toBe('/admin/multiaddrs');
+  });
+
+  it('pushInviteAddresses PUTs /admin/invite-addresses', async () => {
+    const client = makeClient();
+    await client.pushInviteAddresses(['/dns4/h/tcp/1/p2p/x']);
+    expect(last?.method).toBe('PUT');
+    expect(last?.path).toBe('/admin/invite-addresses');
+    expect(JSON.parse(last!.body)).toEqual({ addresses: ['/dns4/h/tcp/1/p2p/x'] });
+  });
+
+  it('encodeInvite mirrors cadre-core base64url(JSON)', () => {
+    const client = makeClient();
+    const invite = { partyId: 'p', authorityAddrs: [], token: 't', createdAt: 1 };
+    const encoded = client.encodeInvite(invite);
+    const decoded = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+    expect(decoded).toEqual(invite);
+  });
+
+  it('maps a non-2xx response to AuthorityNodeUnavailableError carrying the code', async () => {
+    responder = () => ({ status: 503, payload: { ok: false, error: { code: 'not_ready', message: 'node booting' } } });
+    const client = makeClient();
+    await expect(client.getPeerId()).rejects.toBeInstanceOf(AuthorityNodeUnavailableError);
+    await expect(client.getPeerId()).rejects.toMatchObject({ nodeCode: 'not_ready' });
+  });
+
+  it('maps a refused connection to AuthorityNodeUnavailableError', async () => {
+    // Bind a throwaway server to claim a port, then close it so the address
+    // is guaranteed refused.
+    const tmp = http.createServer();
+    const closedPort = await new Promise<number>((resolve) => {
+      tmp.listen(0, '127.0.0.1', () => {
+        const a = tmp.address();
+        resolve(typeof a === 'object' && a ? a.port : 0);
+      });
+    });
+    await new Promise<void>((resolve) => tmp.close(() => resolve()));
+
+    const client = new AuthorityNodeClient({ baseUrl: `http://127.0.0.1:${closedPort}`, token: TOKEN });
+    await expect(client.getPeerId()).rejects.toBeInstanceOf(AuthorityNodeUnavailableError);
+  });
+
+  it('throws AuthorityNodeUnavailableError when the endpoint is undefined', async () => {
+    const client = new AuthorityNodeClient(() => undefined);
+    await expect(client.getPeerId()).rejects.toBeInstanceOf(AuthorityNodeUnavailableError);
+  });
+});

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

@@ -0,0 +1,199 @@
+/**
+ * HTTP client for the authority node's loopback admin channel (the 6.6
+ * `cadre-node-admin-channel` contract).
+ *
+ * cadre-host's manager process holds no in-process `CadreNode`; it spawns the
+ * admin's authority node as a managed child (see `HostProcessOrchestrator`)
+ * and delegates all authority/membership/identity operations to it over this
+ * client. The client implements **both** trimmed `CadreNodeLike` interfaces —
+ * the trust-circle one (`auth/trust-circle.ts`) and the NAT one
+ * (`nat/nat-service.ts`) — plus `pushInviteAddresses`.
+ *
+ * Transport: `Authorization: Bearer <token>` against
+ * `http://127.0.0.1:<adminPort>`. Every response uses the cadre-provider
+ * envelope `{ ok: true, data }` / `{ ok: false, error: { code, message } }`.
+ * A refused connection, a transport error, or any non-2xx response surfaces
+ * as {@link AuthorityNodeUnavailableError}; the trust-circle / NAT services
+ * translate that into a `node_unavailable` domain error so the management API
+ * returns a clear 503 rather than a raw 500.
+ */
+
+import debug from 'debug';
+import type { CadreInvite } from '@serfab/cadre-core';
+
+import type { AuthorityAdminEndpoint } from '../orchestrator/index.js';
+import type { CadreNodeLike as TrustCircleCadreNodeLike } from '../auth/trust-circle.js';
+import type { CadreNodeLike as NatCadreNodeLike } from '../nat/nat-service.js';
+
+const log = debug('cadre:host:authority-client');
+
+/**
+ * Raised when the authority node's admin channel can't be reached or returns
+ * a non-success response. Carries the node's stable error `code` when one was
+ * present in the envelope (e.g. `not_ready`, `not_authorized`).
+ */
+export class AuthorityNodeUnavailableError extends Error {
+  /** The admin-channel error code, when the node answered with an envelope. */
+  readonly nodeCode?: string;
+
+  constructor(message: string, nodeCode?: string) {
+    super(message);
+    this.name = 'AuthorityNodeUnavailableError';
+    if (nodeCode !== undefined) this.nodeCode = nodeCode;
+  }
+}
+
+/** Endpoint provided directly or via a getter (so it tracks re-spawns). */
+type EndpointSource =
+  | AuthorityAdminEndpoint
+  | (() => AuthorityAdminEndpoint | undefined)
+  | undefined;
+
+export interface AuthorityNodeClientOptions {
+  /** Fetch override for tests. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+export class AuthorityNodeClient implements TrustCircleCadreNodeLike, NatCadreNodeLike {
+  private readonly endpointSource: EndpointSource;
+  private readonly fetchImpl: typeof fetch;
+
+  /**
+   * @param endpoint Either a fixed `{ baseUrl, token }` or a getter returning
+   *   the current endpoint (pass `orchestrator.getAuthorityAdminEndpoint`
+   *   bound, so a restart's new bearer token is picked up automatically).
+   */
+  constructor(endpoint: EndpointSource, opts: AuthorityNodeClientOptions = {}) {
+    this.endpointSource = endpoint;
+    this.fetchImpl = opts.fetch ?? fetch;
+  }
+
+  // --- trust-circle CadreNodeLike ---
+
+  async createInvite(
+    token?: string,
+    expiresInMs?: number,
+  ): Promise<{ invite: CadreInvite; encodedInvite: string }> {
+    const body: Record<string, unknown> = {};
+    if (token !== undefined) body.token = token;
+    if (expiresInMs !== undefined) body.expiresInMs = expiresInMs;
+    return await this.request<{ invite: CadreInvite; encodedInvite: string }>(
+      'POST',
+      '/admin/invites',
+      body,
+    );
+  }
+
+  async acceptPhone(
+    options: { phonePeerId: string; token?: string },
+    issuedInvite?: CadreInvite,
+  ): Promise<void> {
+    const body: Record<string, unknown> = { phonePeerId: options.phonePeerId };
+    if (options.token !== undefined) body.token = options.token;
+    if (issuedInvite !== undefined) body.issuedInvite = issuedInvite;
+    await this.request('POST', '/admin/accept-phone', body);
+  }
+
+  async removePeer(peerId: string): Promise<void> {
+    await this.request('DELETE', `/admin/members/${encodeURIComponent(peerId)}`);
+  }
+
+  /**
+   * Encode an invite for out-of-band delivery. The admin contract has no
+   * encode route (the mint route already returns `encodedInvite`), so this
+   * mirrors cadre-core's encoding (`base64url(JSON.stringify(invite))`).
+   */
+  encodeInvite(invite: CadreInvite): string {
+    return Buffer.from(JSON.stringify(invite), 'utf8').toString('base64url');
+  }
+
+  async listMembers(): Promise<Array<{ peerId: string; multiaddr: string | null }>> {
+    const data = await this.request<{ members: Array<{ peerId: string; multiaddr: string | null }> }>(
+      'GET',
+      '/admin/members',
+    );
+    return data.members;
+  }
+
+  async isMember(peerId: string): Promise<boolean> {
+    const data = await this.request<{ member: boolean }>(
+      'GET',
+      `/admin/members/${encodeURIComponent(peerId)}`,
+    );
+    return data.member;
+  }
+
+  // --- NAT CadreNodeLike ---
+
+  async getPeerId(): Promise<string> {
+    const data = await this.request<{ peerId: string | null; partyId: string }>('GET', '/admin/identity');
+    return data.peerId ?? '';
+  }
+
+  async getMultiaddrs(): Promise<string[]> {
+    const data = await this.request<{ multiaddrs: string[] }>('GET', '/admin/multiaddrs');
+    return data.multiaddrs;
+  }
+
+  // --- push-model invite addresses ---
+
+  /** Push the NAT-resolved addresses the node should embed in future invites. */
+  async pushInviteAddresses(addresses: string[]): Promise<void> {
+    await this.request('PUT', '/admin/invite-addresses', { addresses });
+  }
+
+  // --- internals ---
+
+  private resolveEndpoint(): AuthorityAdminEndpoint {
+    const ep = typeof this.endpointSource === 'function' ? this.endpointSource() : this.endpointSource;
+    if (!ep) {
+      throw new AuthorityNodeUnavailableError('Authority node admin endpoint is not available');
+    }
+    return ep;
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const ep = this.resolveEndpoint();
+    const headers: Record<string, string> = { authorization: `Bearer ${ep.token}` };
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) {
+      headers['content-type'] = 'application/json';
+      init.body = JSON.stringify(body);
+    }
+
+    let res: Response;
+    try {
+      res = await this.fetchImpl(`${ep.baseUrl}${path}`, init);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log('admin %s %s transport error: %s', method, path, message);
+      throw new AuthorityNodeUnavailableError(`Authority node unreachable: ${message}`);
+    }
+
+    const envelope = await this.parseEnvelope(res);
+    if (!res.ok || !envelope.ok) {
+      const code = envelope.error?.code;
+      const message = envelope.error?.message ?? `admin ${method} ${path} → HTTP ${res.status}`;
+      log('admin %s %s failed: [%s] %s', method, path, code ?? res.status, message);
+      throw new AuthorityNodeUnavailableError(message, code);
+    }
+    return envelope.data as T;
+  }
+
+  private async parseEnvelope(res: Response): Promise<{
+    ok?: boolean;
+    data?: unknown;
+    error?: { code?: string; message?: string };
+  }> {
+    try {
+      const parsed = await res.json();
+      if (parsed && typeof parsed === 'object') {
+        return parsed as { ok?: boolean; data?: unknown; error?: { code?: string; message?: string } };
+      }
+    } catch {
+      // Non-JSON body — fall through to an empty envelope; status drives the
+      // ok/non-ok decision in the caller.
+    }
+    return {};
+  }
+}

package/src/authority/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Authority-node delegation surface for cadre-host.
+ *
+ * The manager process spawns the admin's authority cadre node (via
+ * `HostProcessOrchestrator`) and delegates authority/membership/identity
+ * operations to it over the loopback admin channel using
+ * {@link AuthorityNodeClient}. See `docs/cadre-host.md` § Control-plane
+ * separation.
+ */
+
+export { AuthorityNodeClient, AuthorityNodeUnavailableError } from './authority-node-client.js';
+export type { AuthorityNodeClientOptions } from './authority-node-client.js';