@serfab/cadre-host 1.13.0 → 1.14.0

package/src/server/routes/trust-circle.ts

@@ -1,49 +0,0 @@
-/**
- * Trust-circle HTTP routes — thin adapters around `TrustCircleHandlers`
- * (`createTrustCircleHandlers(service)`). Side-effects (invite issued,
- * pending revoked, member removed) emit a `trust-circle-changed` bus
- * event so the SPA can refresh without polling.
- *
- * Mount path: `/auth/*` — the existing CLI (cadre-host invite / trust)
- * already targets these URLs; do not change them.
- */
-
-import type { FastifyInstance } from 'fastify';
-
-import type { TrustCircleHandlers } from '../../auth/types.js';
-import type { EventBus } from '../events/bus.js';
-
-export interface TrustCircleRoutesOptions {
-  handlers: TrustCircleHandlers;
-  events: EventBus;
-}
-
-export function registerTrustCircleRoutes(app: FastifyInstance, opts: TrustCircleRoutesOptions): void {
-  const { handlers, events } = opts;
-
-  app.get('/auth/trust-circle', async () => {
-    return handlers.listTrustCircle();
-  });
-
-  app.post('/auth/invites', async (request) => {
-    const body = (request.body ?? {}) as { label?: unknown; ttlMs?: unknown };
-    const label = typeof body.label === 'string' ? body.label : '';
-    const ttlMs = typeof body.ttlMs === 'number' ? body.ttlMs : undefined;
-    const args = ttlMs !== undefined ? { label, ttlMs } : { label };
-    const result = await handlers.postInvite(args);
-    events.publish({ type: 'trust-circle-changed', kind: 'invited' });
-    return result;
-  });
-
-  app.delete<{ Params: { token: string } }>('/auth/invites/:token', async (request) => {
-    await handlers.deleteInvite(request.params.token);
-    events.publish({ type: 'trust-circle-changed', kind: 'revoked' });
-    return { ok: true };
-  });
-
-  app.delete<{ Params: { peerId: string } }>('/auth/members/:peerId', async (request) => {
-    await handlers.deleteMember(request.params.peerId);
-    events.publish({ type: 'trust-circle-changed', kind: 'revoked' });
-    return { ok: true };
-  });
-}

package/src/strands/__tests__/strand-service.test.ts

@@ -1,165 +0,0 @@
-/**
- * StrandService unit tests — a fake node, no HTTP.
- *
- * The two things this layer actually owns: id validation (which must never reach
- * the node) and the translation of the admin channel's single
- * `OwnerNodeUnavailableError` into a vocabulary the HTTP layer can map. The
- * confirmation *policy* is the node's and is not re-tested here — only that the
- * flag is forwarded verbatim.
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-
-import { OwnerNodeUnavailableError } from '../../owner/owner-node-client.js';
-import { StrandService } from '../strand-service.js';
-import { StrandError } from '../types.js';
-import type { CadreNodeLike } from '../strand-service.js';
-import type { StrandListSnapshot, StrandRemovalResult } from '../types.js';
-
-interface FakeNode extends CadreNodeLike {
-  calls: Array<{ strandId: string; confirm: boolean }>;
-  listCalls: number;
-  /** Thrown by both methods when set. */
-  failWith?: unknown;
-}
-
-const SNAPSHOT: StrandListSnapshot = {
-  strands: [
-    { id: 'open-one', type: 'o', running: true, status: 'active' },
-    { id: 'closed-one', type: 'c', running: false, status: null },
-  ],
-  controlConnections: 2,
-};
-
-function fakeNode(): FakeNode {
-  const node: FakeNode = {
-    calls: [],
-    listCalls: 0,
-    async listStrands() {
-      node.listCalls++;
-      if (node.failWith) throw node.failWith;
-      return SNAPSHOT;
-    },
-    async removeStrand(strandId, opts) {
-      node.calls.push({ strandId, confirm: opts.confirm });
-      if (node.failWith) throw node.failWith;
-      const result: StrandRemovalResult = {
-        strandId,
-        published: true,
-        type: 'o',
-        removed: true,
-        alone: false,
-      };
-      return result;
-    },
-  };
-  return node;
-}
-
-/** Await a call expected to reject, assert it is a StrandError, and hand it back. */
-async function catchStrandError(p: Promise<unknown>): Promise<StrandError> {
-  const err = await p.then(() => undefined, (e: unknown) => e);
-  expect(err).toBeInstanceOf(StrandError);
-  return err as StrandError;
-}
-
-let node: FakeNode;
-let service: StrandService;
-
-beforeEach(() => {
-  node = fakeNode();
-  service = new StrandService({ cadreNode: node });
-});
-
-describe('StrandService.list', () => {
-  it('passes the node snapshot through unchanged', async () => {
-    await expect(service.list()).resolves.toEqual(SNAPSHOT);
-    expect(node.listCalls).toBe(1);
-  });
-});
-
-describe('StrandService.remove — id validation', () => {
-  it.each([
-    ['blank', ''],
-    ['whitespace-only', '   '],
-    ['tab/newline only', '\t\n'],
-  ])('rejects a %s id with invalid_id and never calls the node', async (_label, id) => {
-    await expect(service.remove(id, { confirm: false })).rejects.toMatchObject({
-      name: 'StrandError',
-      code: 'invalid_id',
-    });
-    expect(node.calls).toEqual([]);
-  });
-
-  it('forwards an id containing "/" rather than refusing it', async () => {
-    // The whole chain carries it: Fastify decodes `%2F` into `params.id`,
-    // `OwnerNodeClient` re-encodes it, and the admin channel splits on the still
-    // -encoded segment and decodes it back. Refusing here would break the only
-    // form that works. `strands-route.test.ts` pins the Fastify half.
-    await service.remove('ns/strand', { confirm: true });
-    expect(node.calls).toEqual([{ strandId: 'ns/strand', confirm: true }]);
-  });
-
-  it('trims a padded id before forwarding it', async () => {
-    await service.remove('  spaced  ', { confirm: false });
-    expect(node.calls).toEqual([{ strandId: 'spaced', confirm: false }]);
-  });
-});
-
-describe('StrandService.remove — confirmation forwarding', () => {
-  it('forwards confirm: false as false', async () => {
-    await service.remove('open-one', { confirm: false });
-    expect(node.calls).toEqual([{ strandId: 'open-one', confirm: false }]);
-  });
-
-  it('forwards confirm: true as true', async () => {
-    await service.remove('closed-one', { confirm: true });
-    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: true }]);
-  });
-
-  it('does not retry a refused removal with confirmation added', async () => {
-    node.failWith = new OwnerNodeUnavailableError('needs confirmation', 'confirmation_required');
-    await expect(service.remove('closed-one', { confirm: false })).rejects.toBeInstanceOf(StrandError);
-    // Exactly one attempt, and it carried the caller's flag.
-    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: false }]);
-  });
-});
-
-describe('StrandService — error translation', () => {
-  const cases: Array<{ nodeCode: string | undefined; code: string; keepsMessage: boolean }> = [
-    { nodeCode: 'confirmation_required', code: 'confirmation_required', keepsMessage: true },
-    { nodeCode: 'bad_request', code: 'invalid_id', keepsMessage: true },
-    { nodeCode: 'not_ready', code: 'node_unavailable', keepsMessage: false },
-    { nodeCode: 'not_authorized', code: 'node_unavailable', keepsMessage: false },
-    { nodeCode: undefined, code: 'node_unavailable', keepsMessage: false },
-    { nodeCode: 'internal', code: 'internal', keepsMessage: true },
-    { nodeCode: 'something_new', code: 'internal', keepsMessage: true },
-  ];
-
-  for (const { nodeCode, code, keepsMessage } of cases) {
-    it(`maps nodeCode ${nodeCode ?? '(absent)'} → ${code}`, async () => {
-      const message = `node said ${nodeCode ?? 'nothing'}`;
-      node.failWith = new OwnerNodeUnavailableError(message, nodeCode);
-      const err = await catchStrandError(service.remove('x', { confirm: false }));
-      expect(err.code).toBe(code);
-      if (keepsMessage) {
-        expect(err.message).toBe(message);
-      } else {
-        // Wrapped, but the node's words survive inside.
-        expect(err.message).toContain(message);
-      }
-    });
-  }
-
-  it('translates a transport failure (no nodeCode) on list() too', async () => {
-    node.failWith = new OwnerNodeUnavailableError('Owner node unreachable: ECONNREFUSED');
-    const err = await catchStrandError(service.list());
-    expect(err.code).toBe('node_unavailable');
-  });
-
-  it('rethrows a non-owner-node error unchanged rather than dressing it as a strand error', async () => {
-    const boom = new TypeError('something else broke');
-    node.failWith = boom;
-    await expect(service.list()).rejects.toBe(boom);
-  });
-});

package/src/strands/index.ts

@@ -1,14 +0,0 @@
-/**
- * Strand management for cadre-host. See ./strand-service.ts and ./types.ts.
- */
-
-export { StrandService, createStrandHandlers } from './strand-service.js';
-export type { StrandServiceOptions, CadreNodeLike } from './strand-service.js';
-export { StrandError } from './types.js';
-export type {
-  StrandSummary,
-  StrandListSnapshot,
-  StrandRemovalResult,
-  StrandHandlers,
-  StrandErrorCode,
-} from './types.js';

package/src/strands/strand-service.ts

@@ -1,135 +0,0 @@
-import debug from 'debug';
-
-import { OwnerNodeUnavailableError } from '../owner/owner-node-client.js';
-
-import type {
-  StrandHandlers,
-  StrandListSnapshot,
-  StrandRemovalResult,
-} from './types.js';
-import { StrandError } from './types.js';
-
-const log = debug('cadre:host:strands');
-
-/**
- * Minimal slice of the owner node that StrandService uses. Declared here (rather
- * than reaching into `OwnerNodeClient`) so unit tests can inject a fake without
- * standing up an admin channel — the third such trimmed interface the client
- * satisfies, alongside the trust-circle and NAT ones.
- */
-export interface CadreNodeLike {
-  listStrands(): Promise<StrandListSnapshot>;
-  removeStrand(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult>;
-}
-
-/** Constructor options. */
-export interface StrandServiceOptions {
-  /** The owner node — provides listStrands / removeStrand over the admin channel. */
-  cadreNode: CadreNodeLike;
-}
-
-/**
- * StrandService — validation and error translation over the owner node's strand
- * admin routes.
- *
- * It owns no state and makes no policy. In particular it does NOT decide whether a
- * closed strand needs confirmation: it never reads the row, so it could only guess.
- * The node enforces that rule and answers `confirmation_required`; this layer
- * forwards the caller's flag verbatim and surfaces the refusal as a distinct code
- * so the UI can raise the right dialog.
- */
-export class StrandService {
-  private readonly cadreNode: CadreNodeLike;
-
-  constructor(opts: StrandServiceOptions) {
-    this.cadreNode = opts.cadreNode;
-  }
-
-  /** This party's strands, plus the node's current control-connection count. */
-  async list(): Promise<StrandListSnapshot> {
-    return await this.cadreNode.listStrands().catch((err: unknown) => toDomainError(err));
-  }
-
-  /**
-   * Remove this party's participation in one strand.
-   *
-   * `confirm` is forwarded exactly as given — never defaulted to true, never
-   * re-sent as true after a refusal. A closed strand's row carries this party's
-   * membership key for that network and is stored nowhere else, so an automatic
-   * retry would destroy it on the caller's behalf.
-   */
-  async remove(rawId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult> {
-    const strandId = validateStrandId(rawId);
-    log('remove %s (confirm=%s)', strandId, opts.confirm);
-    return await this.cadreNode
-      .removeStrand(strandId, { confirm: opts.confirm })
-      .catch((err: unknown) => toDomainError(err));
-  }
-}
-
-/**
- * Trim and reject an id this surface cannot act on. Blank is the only such id.
- *
- * A `/` is deliberately NOT refused. `/api/strands/:id` is one path segment, but a
- * caller that percent-encodes the id reaches this layer with the `/` restored
- * (Fastify decodes `params`), `OwnerNodeClient` re-encodes it, and the admin channel
- * splits on the still-encoded `%2F` and decodes it back — so the whole chain carries
- * it. Refusing here would break the only form that works, while doing nothing about
- * an UNencoded `/`, which never reaches this handler at all (the router 404s it).
- */
-function validateStrandId(rawId: string): string {
-  const strandId = typeof rawId === 'string' ? rawId.trim() : '';
-  if (!strandId) {
-    throw new StrandError('invalid_id', 'A strand id is required');
-  }
-  return strandId;
-}
-
-/**
- * Translate an owner-node failure into the strand error vocabulary.
- *
- * `OwnerNodeUnavailableError` is thrown for *every* non-ok admin response, not only
- * for a node that is down — so read `nodeCode` first and fall back to
- * `node_unavailable` only when nothing better fits. Reporting a 428 as "your node is
- * down" would be actively misleading.
- *
- * Declared to return `never` so callers can `.catch((err) => toDomainError(err))`.
- *
- * NOTE: the trust-circle and NAT services translate the SAME error blanket-style —
- * every `OwnerNodeUnavailableError` becomes `node_unavailable` — because neither has
- * a code worth distinguishing yet. If a second surface ever needs a code-aware
- * mapping, hoist this switch into a shared owner-error translator instead of growing
- * a third copy.
- */
-function toDomainError(err: unknown): never {
-  if (!(err instanceof OwnerNodeUnavailableError)) {
-    throw err instanceof Error ? err : new Error(String(err));
-  }
-  switch (err.nodeCode) {
-    case 'confirmation_required':
-      throw new StrandError('confirmation_required', err.message);
-    case 'bad_request':
-      throw new StrandError('invalid_id', err.message);
-    case undefined:
-    case 'not_ready':
-    case 'not_authorized':
-      throw new StrandError('node_unavailable', `Owner node unavailable: ${err.message}`);
-    default:
-      throw new StrandError('internal', err.message);
-  }
-}
-
-/**
- * Wrap a StrandService into the typed handler shape the local UI server mounts.
- * Errors propagate as StrandError; `server/error-handler.ts` maps `.code` → status.
- */
-export function createStrandHandlers(service: StrandService): StrandHandlers {
-  return {
-    async listStrands() {
-      return await service.list();
-    },
-    async removeStrand(strandId, opts) {
-      return await service.remove(strandId, { confirm: opts.confirm === true });
-    },
-  };
-}

package/src/strands/types.ts

@@ -1,102 +0,0 @@
-/**
- * Strand-management types for cadre-host.
- *
- * A *strand* is a shared data network this party participates in. Membership is
- * canonical in the cadre control network's `Strand` table, reached over the owner
- * node's loopback admin channel (`GET /admin/strands`,
- * `DELETE /admin/strands/:id?confirm=1`).
- *
- * Unlike the trust circle — which layers host-local labels and pending invites on
- * top of the node's state — this layer holds **no host-local state at all**. There
- * is no `strands.json`. It exists for id validation, for translating the admin
- * channel's error codes into a stable vocabulary the management API can map to HTTP
- * statuses, and for nothing else. Keep it small.
- */
-
-/** One strand this party belongs to, as projected by the admin channel. */
-export interface StrandSummary {
-  /** The `Strand` row id — what a removal takes. */
-  id: string;
-  /** `'o'` = open, `'c'` = closed (the row carries this party's membership key). */
-  type: 'o' | 'c';
-  /** Whether the owner node currently has a running instance for the id. */
-  running: boolean;
-  /**
-   * The instance's status when running, else `null`. Deliberately `string` rather
-   * than cadre-core's `StrandStatus`: this is a wire projection the manager only
-   * forwards, and widening it keeps cadre-host from tracking a cadre-core union it
-   * never inspects.
-   */
-  status: string | null;
-}
-
-/** The result of listing this party's strands. */
-export interface StrandListSnapshot {
-  strands: StrandSummary[];
-  /**
-   * Open control-network connections on the owner node; 0 ⇒ writes commit
-   * local-only. A snapshot at read time, not a subscription — treat it as advisory.
-   */
-  controlConnections: number;
-}
-
-/** The result of removing this party's participation in one strand. */
-export interface StrandRemovalResult {
-  /** The trimmed id the call was about. */
-  strandId: string;
-  /** Whether a row existed before the write. */
-  published: boolean;
-  /** The found row's type; `null` when no row was found. */
-  type: 'o' | 'c' | null;
-  /**
-   * Whether THIS call issued the delete — not that the row was observed to vanish.
-   * The node's read and write are not atomic, so a concurrent removal landing in
-   * between makes this a no-op that still reports `true`.
-   */
-  removed: boolean;
-  /**
-   * The node saw 0 control connections at the end of the call. Sampled on EVERY
-   * call, including one that found no row and wrote nothing — read it as "this
-   * machine currently sees no siblings", and only as "your delete may not have
-   * travelled" when `removed` is also true.
-   */
-  alone: boolean;
-}
-
-/** Error codes thrown by StrandService. */
-export type StrandErrorCode =
-  /** The id was blank or whitespace-only, here or at the node. */
-  | 'invalid_id'
-  /** The node refused a closed-strand removal that carried no confirmation. */
-  | 'confirmation_required'
-  /** The owner node's admin channel is unreachable / not ready. */
-  | 'node_unavailable'
-  /** The node answered with a code this layer has no better word for. */
-  | 'internal';
-
-/** Typed error carrying a stable `code` for HTTP mapping. */
-export class StrandError extends Error {
-  readonly code: StrandErrorCode;
-
-  constructor(code: StrandErrorCode, message: string) {
-    super(message);
-    this.name = 'StrandError';
-    this.code = code;
-  }
-}
-
-/**
- * Typed handlers exposed to the local UI server for Fastify wiring.
- *
- * Handlers either return typed results or throw a `StrandError` whose `.code`
- * `server/error-handler.ts` maps to an HTTP status:
- *
- *   - `invalid_id`            → 400
- *   - `confirmation_required` → 428
- *   - `node_unavailable`      → 503
- *   - `internal`              → 500
- */
-export interface StrandHandlers {
-  listStrands(): Promise<StrandListSnapshot>;
-  removeStrand(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult>;
-}