add the officer-headscale sidecar and its server registry ui

officer-headscale owns the whole Headscale contract: the registered servers and
their admin api keys, the >=0.29 version floor, and every multi-call composition
the ui needs. the platform side is auth+forward only and holds no headscale
credentials, so the existing /api/vpn/enroll route and its HEADSCALE_* env vars
are untouched and unrelated.

officer manages many servers rather than one. the owner registers each with a url
and a key generated on that server and switches between them; exactly one is
active, enforced by a partial unique index rather than by convention. keys are
encrypted at rest and never leave the sidecar — the list projection cannot return
one. registration validates before it saves: an unauthenticated GET /version to
prove something headscale-shaped is there and meets the floor, then an
authenticated call to prove the key works. an edit that moves either half
re-validates.

there is deliberately no transparent /api/v1/* passthrough. headscale serialises
every uint64 as a json string and its rest shape moved repeatedly below 0.29;
proxying raw would push all of that into the browser, which is the mistake the
soulseek panels made with 37 raw upstream calls.

the /headscale workspace is nav + view over the panel system. only the servers
section is implemented — nodes, users and pre-auth keys say so plainly rather
than rendering an empty table that reads as a failed fetch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/servers/sidecar/headscale/index.ts

@@ -0,0 +1,123 @@
+import type { SidecarCommand, SidecarEvent } from '../protocol';
+import { createSidecarConnector } from '../connect';
+import { handleOfficerRoute } from './routes';
+import { MIN_VERSION_LABEL } from './version';
+
+// The officer-headscale sidecar. Owns the whole Headscale contract for Officer: the registered servers and
+// their admin API keys, the >=0.29 version floor, and every multi-call composition the UI needs. The platform
+// API is a thin auth-gated forwarder (src/servers/api/headscale/router.ts) holding no Headscale credentials.
+//
+// Officer manages MANY Headscale servers, not one. The owner registers each with a URL and an API key
+// generated on that server, and switches between them; one is active at a time. So configuration lives in
+// Postgres (headscale_servers, keys encrypted at rest), NOT in env vars — this sidecar deliberately reads
+// neither HEADSCALE_URL nor HEADSCALE_API_KEY, so a registered server can never be shadowed by host env.
+// (Those two vars belong solely to the unrelated /api/vpn/enroll route, which is none of our business.)
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// HTTP CONTRACT — the platform strips its /api/headscale mount prefix before forwarding.
+//
+//   GET /_health                          ours. Sidecar liveness only. Per-server reachability is a
+//                                         different question and needs an owner, so it lives below.
+//   GET    /_officer/servers              registered servers (never includes API keys)
+//   POST   /_officer/servers              register {name?,url,apiKey} — validated before it is saved
+//   PATCH  /_officer/servers/:id          edit; re-validated when url or apiKey changes
+//   DELETE /_officer/servers/:id          deregister; promotes the newest survivor if it was active
+//   POST   /_officer/servers/:id/activate switch the active server
+//   GET    /_officer/servers/:id/health   probe: reachable? version? key still accepted?
+//   anything else                         404
+//
+// There is deliberately NO transparent /api/v1/* passthrough. Headscale's REST shape changed repeatedly
+// below 0.29 and its ids are uint64-as-JSON-string, so proxying raw would push all of that into the browser
+// — the mistake the Soulseek panels made with 37 raw upstream calls. Every quirk is absorbed here.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+const API_URL = process.env.API_URL ?? `ws://127.0.0.1:${process.env.PORT ?? '5000'}`;
+
+/** Grab an ephemeral free port by briefly binding one and releasing it. */
+function getFreePort(): number {
+  const probe = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') });
+  const p = probe.port;
+  probe.stop(true);
+  if (p == null) throw new Error('failed to acquire a free port');
+  return p;
+}
+
+const port = getFreePort();
+
+const server = Bun.serve({
+  port,
+  hostname: '127.0.0.1',
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    // Liveness, not upstream health: with many registered servers there is no single upstream to probe, and
+    // choosing one would need an authenticated owner. See /_officer/servers/:id/health for that.
+    if (url.pathname === '/_health') {
+      return Response.json({ ok: true, minHeadscaleVersion: MIN_VERSION_LABEL });
+    }
+
+    if (url.pathname.startsWith('/_officer/')) {
+      try {
+        const res = await handleOfficerRoute(req, url);
+        return res ?? new Response('not found', { status: 404 });
+      } catch (err) {
+        console.error(`[headscale] ${req.method} ${url.pathname} failed`, err);
+        return Response.json({ error: 'internal error' }, { status: 500 });
+      }
+    }
+
+    return new Response('not found', { status: 404 });
+  },
+});
+
+console.log(`[headscale] listening on 127.0.0.1:${port} (Headscale >=${MIN_VERSION_LABEL})`);
+
+// ── Command handlers ──
+
+type ReplyFn = (msg: SidecarEvent) => void;
+
+function handleCommand(cmd: SidecarCommand, reply: ReplyFn) {
+  switch (cmd.type) {
+    case 'ping':
+      reply({ type: 'pong', id: cmd.id });
+      break;
+    default:
+      reply({
+        type: 'error',
+        id: (cmd as SidecarCommand).id,
+        error: `Unknown command type: ${(cmd as Record<string, unknown>).type}`,
+      });
+  }
+}
+
+// ── Connect to API server ──
+
+const connection = createSidecarConnector({
+  apiUrl: `${API_URL}/api/sidecar/register`,
+  name: 'headscale',
+  capabilities: ['headscale'],
+  onCommand(cmd, reply) {
+    handleCommand(cmd as SidecarCommand, reply as ReplyFn);
+  },
+  onConnected() {
+    // Tell the API where we're listening, so it can forward /api/headscale/* here.
+    connection.send({ type: 'headscale:server', port });
+    console.log(`[headscale] reported port ${port} to API`);
+  },
+});
+
+// ── Graceful shutdown ──
+
+function shutdown(signal: string) {
+  console.log(`[headscale] ${signal} received, shutting down...`);
+  try {
+    server.stop(true);
+  } catch {
+    /* already stopped */
+  }
+  connection.destroy();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));