@serfab/cadre-host 0.9.0 → 0.11.0

package/src/server/static.ts

@@ -1,207 +1,207 @@
-/**
- * Static-asset mount for the SPA bundle.
- *
- * The SPA bundle is produced by `6.5.2-cadre-host-local-ui-spa` into
- * `<package>/dist/ui/`. When that directory exists we serve files from it
- * with an `index.html` SPA fallback. When it's missing (running from source
- * before the SPA ticket lands) we serve a placeholder page that explains
- * how to install/build the SPA.
- *
- * Hand-rolled rather than pulling in `@fastify/static` — the surface area we
- * need is tiny and the dep would only matter under tests that don't exercise
- * static serving anyway.
- */
-
-import { readFileSync, statSync, existsSync } from 'node:fs';
-import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
-
-const MIME_TYPES: Record<string, string> = {
-  '.html': 'text/html; charset=utf-8',
-  '.js': 'application/javascript; charset=utf-8',
-  '.mjs': 'application/javascript; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.txt': 'text/plain; charset=utf-8',
-  '.map': 'application/json; charset=utf-8',
-};
-
-/**
- * Default location of the SPA bundle when `cadre-host` runs from its
- * installed package.
- * - dist/server/static.js → ../ui  → packages/cadre-host/dist/ui
- */
-export function defaultStaticRoot(): string {
-  const here = dirname(fileURLToPath(import.meta.url));
-  return resolve(here, '..', 'ui');
-}
-
-export interface StaticMountOptions {
-  /** Absolute path to the SPA build output (defaults to `defaultStaticRoot()`). */
-  rootDir?: string;
-}
-
-export function registerStaticMount(app: FastifyInstance, opts: StaticMountOptions = {}): void {
-  const rootDir = opts.rootDir ?? defaultStaticRoot();
-
-  // Register *after* all routes so API paths win.
-  app.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
-    if (request.method !== 'GET' && request.method !== 'HEAD') {
-      return reply.code(404).send({
-        ok: false,
-        error: { code: 'not_found', message: `No route for ${request.method} ${request.url}` },
-      });
-    }
-    // Don't try to serve API paths as static.
-    if (
-      request.url.startsWith('/api') ||
-      request.url.startsWith('/auth') ||
-      request.url.startsWith('/nat') ||
-      request.url.startsWith('/update')
-    ) {
-      return reply.code(404).send({
-        ok: false,
-        error: { code: 'not_found', message: `No route for ${request.method} ${request.url}` },
-      });
-    }
-    return serveStatic(rootDir, request, reply);
-  });
-}
-
-function serveStatic(rootDir: string, request: FastifyRequest, reply: FastifyReply): FastifyReply {
-  if (!existsSync(rootDir)) {
-    if (request.url === '/' || request.url === '/index.html') {
-      return reply.code(200).type('text/html; charset=utf-8').send(placeholderHtml());
-    }
-    return reply.code(404).send({
-      ok: false,
-      error: { code: 'not_found', message: 'SPA bundle not installed' },
-    });
-  }
-
-  const requested = stripQuery(request.url);
-  const target = resolveSafe(rootDir, requested);
-  if (!target) {
-    return reply.code(404).send({
-      ok: false,
-      error: { code: 'not_found', message: `No static asset for ${request.url}` },
-    });
-  }
-  try {
-    const stat = statSync(target);
-    if (stat.isFile()) return sendFile(reply, target);
-  } catch {
-    // fall through to SPA index
-  }
-  // SPA fallback: serve index.html for any GET that accepts HTML.
-  const accept = (request.headers.accept ?? '').toLowerCase();
-  if (accept.includes('text/html') || accept === '' || accept === '*/*') {
-    const index = join(rootDir, 'index.html');
-    if (existsSync(index)) return sendFile(reply, index);
-  }
-  return reply.code(404).send({
-    ok: false,
-    error: { code: 'not_found', message: `No static asset for ${request.url}` },
-  });
-}
-
-/**
- * Resolve a request path to an absolute file path inside `rootDir`, or `null`
- * if it would escape the root.
- *
- * Exported for direct unit testing. The containment check uses `path.relative`
- * rather than a bare `startsWith` prefix test: the latter is the classic
- * prefix-bypass anti-pattern, accepting sibling directories whose name shares
- * `rootDir`'s basename as a prefix (e.g. `dist/ui-private` vs `dist/ui`).
- * `relative` respects the path-separator boundary on both POSIX and Windows,
- * and surfaces cross-drive escapes on Windows as an absolute result.
- */
-export function resolveSafe(rootDir: string, urlPath: string): string | null {
-  const cleaned = decodeSafe(urlPath);
-  if (cleaned === null) return null;
-  const root = normalize(rootDir);
-  const target = normalize(join(root, cleaned === '/' ? '' : cleaned));
-  // Containment: target must be rootDir itself or strictly beneath it.
-  // `relative(root, target)` is '' for root itself (accepted) and a descendant
-  // path with no leading '..' for in-root assets. Reject when it climbs out
-  // (exactly '..', or '..' + separator) or — cross-drive on Windows — is
-  // absolute. Guarding on '..' + separator rather than a bare '..' prefix avoids
-  // falsely rejecting legitimate in-root names that merely *begin* with '..'
-  // (e.g. a '..foo' asset), which would re-introduce a looser prefix check.
-  const rel = relative(root, target);
-  if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) return null;
-  return target;
-}
-
-function decodeSafe(urlPath: string): string | null {
-  try {
-    const decoded = decodeURIComponent(urlPath);
-    if (decoded.includes('\0')) return null;
-    return decoded;
-  } catch {
-    return null;
-  }
-}
-
-function stripQuery(url: string): string {
-  const q = url.indexOf('?');
-  return q === -1 ? url : url.slice(0, q);
-}
-
-function sendFile(reply: FastifyReply, path: string): FastifyReply {
-  const buf = readFileSync(path);
-  const mime = MIME_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
-  return reply.code(200).type(mime).send(buf);
-}
-
-function placeholderHtml(): string {
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>cadre-host — UI bundle missing</title>
-    <style>
-      body { font-family: system-ui, -apple-system, sans-serif; max-width: 40rem; margin: 4rem auto; padding: 0 1rem; color: #1a1a1a; }
-      h1 { font-weight: 600; }
-      code { background: #f4f4f4; padding: 0.125rem 0.375rem; border-radius: 0.25rem; }
-      pre { background: #f4f4f4; padding: 0.75rem 1rem; border-radius: 0.5rem; overflow: auto; }
-      .endpoint { font-family: ui-monospace, monospace; }
-    </style>
-  </head>
-  <body>
-    <h1>cadre-host is running — UI bundle is missing</h1>
-    <p>
-      The HTTP management API is fully available (see endpoints below), but the
-      Svelte SPA that normally renders at this URL hasn't been built into this
-      install. This page is most likely shown because the package was started
-      from a source checkout without running the UI build step.
-    </p>
-    <p>To build it:</p>
-    <pre>yarn workspace @serfab/cadre-host build</pre>
-    <p>or just the UI:</p>
-    <pre>yarn workspace @serfab/cadre-host build:ui</pre>
-    <p>Then refresh this page.</p>
-
-    <h2 style="font-size:1.1rem;margin-top:2rem;">Available API endpoints</h2>
-    <ul>
-      <li><span class="endpoint">GET /api/status</span></li>
-      <li><span class="endpoint">GET /api/nodes</span></li>
-      <li><span class="endpoint">GET /api/settings</span></li>
-      <li><span class="endpoint">GET /api/events</span> (Server-Sent Events)</li>
-      <li><span class="endpoint">/auth/*</span>, <span class="endpoint">/nat/*</span>, <span class="endpoint">/update/*</span></li>
-    </ul>
-    <p>See <a href="https://github.com/gotchoices/sereus/blob/master/docs/cadre-host.md">docs/cadre-host.md</a>.</p>
-  </body>
-</html>
-`;
-}
+/**
+ * Static-asset mount for the SPA bundle.
+ *
+ * The SPA bundle is produced by `6.5.2-cadre-host-local-ui-spa` into
+ * `<package>/dist/ui/`. When that directory exists we serve files from it
+ * with an `index.html` SPA fallback. When it's missing (running from source
+ * before the SPA ticket lands) we serve a placeholder page that explains
+ * how to install/build the SPA.
+ *
+ * Hand-rolled rather than pulling in `@fastify/static` — the surface area we
+ * need is tiny and the dep would only matter under tests that don't exercise
+ * static serving anyway.
+ */
+
+import { readFileSync, statSync, existsSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.txt': 'text/plain; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+};
+
+/**
+ * Default location of the SPA bundle when `cadre-host` runs from its
+ * installed package.
+ * - dist/server/static.js → ../ui  → packages/cadre-host/dist/ui
+ */
+export function defaultStaticRoot(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', 'ui');
+}
+
+export interface StaticMountOptions {
+  /** Absolute path to the SPA build output (defaults to `defaultStaticRoot()`). */
+  rootDir?: string;
+}
+
+export function registerStaticMount(app: FastifyInstance, opts: StaticMountOptions = {}): void {
+  const rootDir = opts.rootDir ?? defaultStaticRoot();
+
+  // Register *after* all routes so API paths win.
+  app.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `No route for ${request.method} ${request.url}` },
+      });
+    }
+    // Don't try to serve API paths as static.
+    if (
+      request.url.startsWith('/api') ||
+      request.url.startsWith('/auth') ||
+      request.url.startsWith('/nat') ||
+      request.url.startsWith('/update')
+    ) {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `No route for ${request.method} ${request.url}` },
+      });
+    }
+    return serveStatic(rootDir, request, reply);
+  });
+}
+
+function serveStatic(rootDir: string, request: FastifyRequest, reply: FastifyReply): FastifyReply {
+  if (!existsSync(rootDir)) {
+    if (request.url === '/' || request.url === '/index.html') {
+      return reply.code(200).type('text/html; charset=utf-8').send(placeholderHtml());
+    }
+    return reply.code(404).send({
+      ok: false,
+      error: { code: 'not_found', message: 'SPA bundle not installed' },
+    });
+  }
+
+  const requested = stripQuery(request.url);
+  const target = resolveSafe(rootDir, requested);
+  if (!target) {
+    return reply.code(404).send({
+      ok: false,
+      error: { code: 'not_found', message: `No static asset for ${request.url}` },
+    });
+  }
+  try {
+    const stat = statSync(target);
+    if (stat.isFile()) return sendFile(reply, target);
+  } catch {
+    // fall through to SPA index
+  }
+  // SPA fallback: serve index.html for any GET that accepts HTML.
+  const accept = (request.headers.accept ?? '').toLowerCase();
+  if (accept.includes('text/html') || accept === '' || accept === '*/*') {
+    const index = join(rootDir, 'index.html');
+    if (existsSync(index)) return sendFile(reply, index);
+  }
+  return reply.code(404).send({
+    ok: false,
+    error: { code: 'not_found', message: `No static asset for ${request.url}` },
+  });
+}
+
+/**
+ * Resolve a request path to an absolute file path inside `rootDir`, or `null`
+ * if it would escape the root.
+ *
+ * Exported for direct unit testing. The containment check uses `path.relative`
+ * rather than a bare `startsWith` prefix test: the latter is the classic
+ * prefix-bypass anti-pattern, accepting sibling directories whose name shares
+ * `rootDir`'s basename as a prefix (e.g. `dist/ui-private` vs `dist/ui`).
+ * `relative` respects the path-separator boundary on both POSIX and Windows,
+ * and surfaces cross-drive escapes on Windows as an absolute result.
+ */
+export function resolveSafe(rootDir: string, urlPath: string): string | null {
+  const cleaned = decodeSafe(urlPath);
+  if (cleaned === null) return null;
+  const root = normalize(rootDir);
+  const target = normalize(join(root, cleaned === '/' ? '' : cleaned));
+  // Containment: target must be rootDir itself or strictly beneath it.
+  // `relative(root, target)` is '' for root itself (accepted) and a descendant
+  // path with no leading '..' for in-root assets. Reject when it climbs out
+  // (exactly '..', or '..' + separator) or — cross-drive on Windows — is
+  // absolute. Guarding on '..' + separator rather than a bare '..' prefix avoids
+  // falsely rejecting legitimate in-root names that merely *begin* with '..'
+  // (e.g. a '..foo' asset), which would re-introduce a looser prefix check.
+  const rel = relative(root, target);
+  if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) return null;
+  return target;
+}
+
+function decodeSafe(urlPath: string): string | null {
+  try {
+    const decoded = decodeURIComponent(urlPath);
+    if (decoded.includes('\0')) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+function stripQuery(url: string): string {
+  const q = url.indexOf('?');
+  return q === -1 ? url : url.slice(0, q);
+}
+
+function sendFile(reply: FastifyReply, path: string): FastifyReply {
+  const buf = readFileSync(path);
+  const mime = MIME_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+  return reply.code(200).type(mime).send(buf);
+}
+
+function placeholderHtml(): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>cadre-host — UI bundle missing</title>
+    <style>
+      body { font-family: system-ui, -apple-system, sans-serif; max-width: 40rem; margin: 4rem auto; padding: 0 1rem; color: #1a1a1a; }
+      h1 { font-weight: 600; }
+      code { background: #f4f4f4; padding: 0.125rem 0.375rem; border-radius: 0.25rem; }
+      pre { background: #f4f4f4; padding: 0.75rem 1rem; border-radius: 0.5rem; overflow: auto; }
+      .endpoint { font-family: ui-monospace, monospace; }
+    </style>
+  </head>
+  <body>
+    <h1>cadre-host is running — UI bundle is missing</h1>
+    <p>
+      The HTTP management API is fully available (see endpoints below), but the
+      Svelte SPA that normally renders at this URL hasn't been built into this
+      install. This page is most likely shown because the package was started
+      from a source checkout without running the UI build step.
+    </p>
+    <p>To build it:</p>
+    <pre>yarn workspace @serfab/cadre-host build</pre>
+    <p>or just the UI:</p>
+    <pre>yarn workspace @serfab/cadre-host build:ui</pre>
+    <p>Then refresh this page.</p>
+
+    <h2 style="font-size:1.1rem;margin-top:2rem;">Available API endpoints</h2>
+    <ul>
+      <li><span class="endpoint">GET /api/status</span></li>
+      <li><span class="endpoint">GET /api/nodes</span></li>
+      <li><span class="endpoint">GET /api/settings</span></li>
+      <li><span class="endpoint">GET /api/events</span> (Server-Sent Events)</li>
+      <li><span class="endpoint">/auth/*</span>, <span class="endpoint">/nat/*</span>, <span class="endpoint">/update/*</span></li>
+    </ul>
+    <p>See <a href="https://github.com/gotchoices/sereus/blob/master/docs/cadre-host.md">docs/cadre-host.md</a>.</p>
+  </body>
+</html>
+`;
+}

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

@@ -0,0 +1,165 @@
+/**
+ * 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

@@ -0,0 +1,14 @@
+/**
+ * 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';