headscale nodes, users and pre-auth key management

domain routes in the sidecar: nodes with per-route approval done as a
read-modify-write (headscale's approve_routes replaces the whole set),
users enriched with node counts, and pre-auth keys.

pre-auth key secrets are revealed by call path, not by inspecting the
value. headscale masks keys created since 0.28, but returns older
plaintext ones in full from the list endpoint for backwards
compatibility, so listing would otherwise ship live secrets into the
browser's query cache. the list always nulls the secret; only creation
reveals it, and the ui shows it once with a copy affordance.

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

src/servers/sidecar/headscale/active.ts

@@ -0,0 +1,20 @@
+import { getActiveHeadscaleCredentials } from 'officerdb';
+import { createClient, type HeadscaleClient } from './client';
+
+// Every domain route acts on the ACTIVE server — the one the owner selected in the servers section. That
+// choice lives in Postgres (one row, enforced by a partial unique index), not in a request parameter, so
+// no client can act on a server the owner isn't currently looking at by guessing an id.
+
+/**
+ * The client for the active server, or a ready-to-send 409 when there isn't one.
+ *
+ * 409 rather than 404: the route exists and the request was well-formed, the account just has no server
+ * selected yet. The UI maps it to "pick a server", which is a different message from "that node is gone".
+ */
+export async function activeClient(userId: number): Promise<HeadscaleClient | Response> {
+  const creds = await getActiveHeadscaleCredentials(userId);
+  if (!creds) {
+    return Response.json({ error: 'no active Headscale server', code: 'no_active_server' }, { status: 409 });
+  }
+  return createClient(creds);
+}

src/servers/sidecar/headscale/index.ts

@@ -24,6 +24,25 @@ import { MIN_VERSION_LABEL } from './version';
 //   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?
+//
+// Everything below acts on the ACTIVE server. 409 when none is selected — see active.ts.
+//
+//   GET    /_officer/nodes                nodes, normalized; ?user=<username> filters
+//   GET    /_officer/nodes/:id            one node
+//   DELETE /_officer/nodes/:id            remove it from the tailnet
+//   POST   /_officer/nodes/:id/rename     {name}
+//   POST   /_officer/nodes/:id/tags       {tags} — 'tag:' prefix added if missing
+//   POST   /_officer/nodes/:id/routes     {routes} whole set, or {route,approved} single toggle (RMW here)
+//   POST   /_officer/nodes/:id/expire     expire its key, forcing re-auth (not a delete)
+//   GET    /_officer/users                users, each with a node count the admin API doesn't provide
+//   POST   /_officer/users                {name, displayName?, email?}
+//   POST   /_officer/users/:id/rename     {name}
+//   DELETE /_officer/users/:id            refused upstream while the user still owns nodes
+//   GET    /_officer/keys                 pre-auth keys, secrets masked, with a derived status
+//   POST   /_officer/keys                 {userId, reusable?, ephemeral?, expirationDays?, aclTags?}
+//                                         → the ONLY response carrying the real secret
+//   POST   /_officer/keys/:id/expire      expire without deleting
+//   DELETE /_officer/keys/:id             delete outright
 //   anything else                         404
 //
 // There is deliberately NO transparent /api/v1/* passthrough. Headscale's REST shape changed repeatedly

src/servers/sidecar/headscale/keys.ts

@@ -0,0 +1,119 @@
+import type { OfficerContext } from './routes';
+import { badRequest, notFound, methodNotAllowed, readJson } from './routes';
+import { activeClient } from './active';
+import { toPreAuthKey, arrayField } from './normalize';
+
+// Pre-auth key routes — /_officer/keys/*. These are the tokens a machine uses to join the tailnet.
+//
+// The one thing that matters here: since 0.28 Headscale stores pre-auth keys HASHED and returns the real
+// secret ONLY in the create response. Every later list returns it masked as `hskey-auth-<prefix>-***`. A
+// creation response that the UI drops is a key the owner can never recover — it has to be shown once, with
+// a copy affordance, and the API has to make the difference legible. `key` is non-null exactly once.
+//
+// That "exactly once" is enforced by call path, not by inspecting the value: keys created before 0.28 are
+// still plaintext upstream and Headscale hands them back in full from the LIST endpoint for backwards
+// compatibility. So listing passes reveal:false and drops the secret unconditionally; only createKey
+// reveals. A server with history in it would otherwise leak live keys into the browser's query cache.
+//
+// Also note the shape of the delete/expire pair: expire takes the id in a POST BODY, delete takes it in a
+// query STRING, and neither is a REST-shaped path. Both are hidden behind ordinary Officer routes.
+
+/** Default lifetime when the caller doesn't pick one; matches Headscale's own CLI default. */
+const DEFAULT_EXPIRY_DAYS = 90;
+const MAX_EXPIRY_DAYS = 3650;
+
+async function listKeys(ctx: OfficerContext): Promise<Response> {
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  // 0.29 lists every user's keys in one call (pre-0.29 required a ?user= filter and one call per user).
+  const body = await client.call('/api/v1/preauthkey');
+  const keys = arrayField(body, 'preAuthKeys').map((raw) => toPreAuthKey(raw, { reveal: false }));
+
+  // Usable keys first, then by newest — a spent key is history, an active one is the thing you came for.
+  const rank = { active: 0, used: 1, expired: 2 } as const;
+  keys.sort((a, b) => rank[a.status] - rank[b.status] || (b.createdAt ?? '').localeCompare(a.createdAt ?? ''));
+
+  return Response.json({ keys });
+}
+
+async function createKey(ctx: OfficerContext): Promise<Response> {
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  const body = await readJson(ctx.req);
+  if (!body) return badRequest('expected a JSON body');
+
+  // CreatePreAuthKey takes a numeric user ID — unlike the node list filter, which takes a username. The
+  // two are easy to confuse and the failure is a confusing upstream error, so it's validated here.
+  const userId = typeof body.userId === 'string' ? body.userId.trim() : '';
+  if (!/^\d+$/.test(userId)) return badRequest('userId must be the numeric id of a Headscale user');
+
+  const days = body.expirationDays === undefined ? DEFAULT_EXPIRY_DAYS : Number(body.expirationDays);
+  if (!Number.isFinite(days) || days <= 0 || days > MAX_EXPIRY_DAYS) {
+    return badRequest(`expirationDays must be between 1 and ${MAX_EXPIRY_DAYS}`);
+  }
+
+  const aclTags = Array.isArray(body.aclTags)
+    ? body.aclTags
+        .filter((t): t is string => typeof t === 'string')
+        .map((t) => t.trim())
+        .filter(Boolean)
+        .map((t) => (t.startsWith('tag:') ? t : `tag:${t}`))
+    : [];
+
+  const created = await client.call<{ preAuthKey?: Record<string, unknown> }>('/api/v1/preauthkey', {
+    method: 'POST',
+    body: {
+      user: userId,
+      reusable: body.reusable === true,
+      ephemeral: body.ephemeral === true,
+      expiration: new Date(Date.now() + days * 86_400_000).toISOString(),
+      aclTags,
+    },
+  });
+
+  if (!created.preAuthKey) return Response.json({ error: 'headscale returned no key' }, { status: 502 });
+
+  const key = toPreAuthKey(created.preAuthKey, { reveal: true });
+  // Stated explicitly rather than left for the client to infer from `key !== null`: this response is the
+  // only time the secret exists anywhere outside the joining machine.
+  return Response.json({ key, secretShownOnce: true }, { status: 201 });
+}
+
+type KeyActionParams = { ctx: OfficerContext; id: string; action: string | undefined };
+
+async function handleKeyAction({ ctx, id, action }: KeyActionParams): Promise<Response> {
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  if (action === 'expire') {
+    if (ctx.req.method !== 'POST') return methodNotAllowed();
+    await client.call('/api/v1/preauthkey/expire', { method: 'POST', body: { id } });
+    return new Response(null, { status: 204 });
+  }
+
+  if (action !== undefined) return notFound();
+
+  if (ctx.req.method === 'DELETE') {
+    await client.call(`/api/v1/preauthkey?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+    return new Response(null, { status: 204 });
+  }
+
+  return methodNotAllowed();
+}
+
+/** Dispatch `/_officer/keys/...`. `rest` is the path after `keys`. */
+export async function handleKeysRoute(ctx: OfficerContext, rest: string[]): Promise<Response> {
+  if (rest.length === 0) {
+    if (ctx.req.method === 'GET') return listKeys(ctx);
+    if (ctx.req.method === 'POST') return createKey(ctx);
+    return methodNotAllowed();
+  }
+  if (rest.length > 2) return notFound();
+
+  const id = rest[0];
+  if (!id || !/^\d+$/.test(id)) return badRequest('key id must be numeric');
+
+  return handleKeyAction({ ctx, id, action: rest[1] });
+}

src/servers/sidecar/headscale/nodes.ts

@@ -0,0 +1,129 @@
+import type { OfficerContext } from './routes';
+import { badRequest, notFound, methodNotAllowed, readJson } from './routes';
+import type { HeadscaleClient } from './client';
+import { activeClient } from './active';
+import { toNode, arrayField, type OfficerNode } from './normalize';
+
+// Node routes — /_officer/nodes/*. A "node" is a machine in the tailnet.
+//
+// Two upstream shapes are worth knowing before reading this:
+//
+//  • Renaming takes the new name in the PATH (`/node/{id}/rename/{newName}`), not a body. It must be
+//    encodeURIComponent'd or a name with a slash silently becomes a 404 on a different route.
+//  • Route approval is a whole-SET write (`approve_routes` replaces the approved list), not an
+//    add/remove. Approving one route means sending every route that should remain approved, so those
+//    operations are read-modify-write here rather than in the browser — see rule 5 in
+//    SIDECAR_ARCHITECTURE.md. Doing it client-side would make two admins racing lose each other's edits;
+//    doing it here still races, but over milliseconds instead of however long a form sits open.
+
+/** Nodes on the active server, newest-registered first within each user. */
+async function listNodes(ctx: OfficerContext): Promise<Response> {
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  // The upstream `user` filter takes a USERNAME, not an id — a trap worth keeping out of the browser.
+  const user = ctx.url.searchParams.get('user');
+  const path = user ? `/api/v1/node?user=${encodeURIComponent(user)}` : '/api/v1/node';
+
+  const body = await client.call(path);
+  const nodes = arrayField(body, 'nodes').map(toNode);
+  nodes.sort((a, b) => Number(b.online) - Number(a.online) || a.name.localeCompare(b.name));
+  return Response.json({ nodes });
+}
+
+/** Re-read one node after a mutation. Headscale's mutation responses are inconsistent; a GET never is. */
+async function getNode(client: HeadscaleClient, id: string): Promise<OfficerNode | null> {
+  const body = await client.call<{ node?: Record<string, unknown> }>(`/api/v1/node/${encodeURIComponent(id)}`);
+  return body.node ? toNode(body.node) : null;
+}
+
+type NodeActionParams = { ctx: OfficerContext; id: string; action: string | undefined };
+
+async function handleNodeAction({ ctx, id, action }: NodeActionParams): Promise<Response> {
+  const { req } = ctx;
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  if (action === undefined) {
+    if (req.method === 'GET') {
+      const node = await getNode(client, id);
+      return node ? Response.json({ node }) : notFound('no such node');
+    }
+    if (req.method === 'DELETE') {
+      await client.call(`/api/v1/node/${encodeURIComponent(id)}`, { method: 'DELETE' });
+      return new Response(null, { status: 204 });
+    }
+    return methodNotAllowed();
+  }
+
+  if (req.method !== 'POST') return methodNotAllowed();
+
+  if (action === 'rename') {
+    const body = await readJson(req);
+    if (!body) return badRequest('expected a JSON body');
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    if (!name) return badRequest('name is required');
+    await client.call(`/api/v1/node/${encodeURIComponent(id)}/rename/${encodeURIComponent(name)}`, { method: 'POST' });
+    return Response.json({ node: await getNode(client, id) });
+  }
+
+  if (action === 'tags') {
+    const body = await readJson(req);
+    if (!body) return badRequest('expected a JSON body');
+    if (!Array.isArray(body.tags)) return badRequest('tags must be an array of strings');
+    const tags = body.tags.filter((t): t is string => typeof t === 'string').map((t) => t.trim());
+    if (tags.some((t) => !t)) return badRequest('tags cannot be empty strings');
+    // Headscale requires the `tag:` prefix and rejects anything else with a 500, which we'd surface as a
+    // useless "headscale error". Normalizing here means the UI can accept either form.
+    const prefixed = tags.map((t) => (t.startsWith('tag:') ? t : `tag:${t}`));
+    await client.call(`/api/v1/node/${encodeURIComponent(id)}/tags`, { method: 'POST', body: { tags: prefixed } });
+    return Response.json({ node: await getNode(client, id) });
+  }
+
+  if (action === 'routes') {
+    const body = await readJson(req);
+    if (!body) return badRequest('expected a JSON body');
+
+    let routes: string[];
+    if (Array.isArray(body.routes)) {
+      // Whole-set write: the caller states the complete approved list.
+      routes = body.routes.filter((r): r is string => typeof r === 'string');
+    } else if (typeof body.route === 'string' && typeof body.approved === 'boolean') {
+      // Single-toggle: read the current set, apply one change, write it back.
+      const current = await getNode(client, id);
+      if (!current) return notFound('no such node');
+      const set = new Set(current.approvedRoutes);
+      if (body.approved) set.add(body.route);
+      else set.delete(body.route);
+      routes = [...set];
+    } else {
+      return badRequest('expected {routes: string[]} or {route: string, approved: boolean}');
+    }
+
+    await client.call(`/api/v1/node/${encodeURIComponent(id)}/approve_routes`, { method: 'POST', body: { routes } });
+    return Response.json({ node: await getNode(client, id) });
+  }
+
+  if (action === 'expire') {
+    // Expires the node's key, forcing it to re-authenticate. Not a delete: the node stays registered.
+    await client.call(`/api/v1/node/${encodeURIComponent(id)}/expire`, { method: 'POST' });
+    return Response.json({ node: await getNode(client, id) });
+  }
+
+  return notFound();
+}
+
+/** Dispatch `/_officer/nodes/...`. `rest` is the path after `nodes`. */
+export async function handleNodesRoute(ctx: OfficerContext, rest: string[]): Promise<Response> {
+  if (rest.length === 0) {
+    if (ctx.req.method !== 'GET') return methodNotAllowed();
+    return listNodes(ctx);
+  }
+  if (rest.length > 2) return notFound();
+
+  const id = rest[0];
+  // Upstream ids are uint64-as-string. Validate the shape without parsing — Number() would lose precision.
+  if (!id || !/^\d+$/.test(id)) return badRequest('node id must be numeric');
+
+  return handleNodeAction({ ctx, id, action: rest[1] });
+}

src/servers/sidecar/headscale/normalize.ts

@@ -0,0 +1,187 @@
+// Officer-shaped views of Headscale's admin API objects, and the quirk handling that gets us there.
+//
+// Headscale's REST layer is a gRPC gateway marshalling protobuf, which leaks in three ways we normalize
+// here so nothing downstream has to know:
+//
+//  1. Every uint64 is a JSON STRING. Ids stay strings end to end — never Number() them, that breaks
+//     silently above 2^53 and Headscale's ids are database-assigned, not small by contract.
+//  2. Unset timestamps are the protobuf zero value, serialized as '0001-01-01T00:00:00Z' rather than
+//     omitted. Rendered naively that reads as the year 1 — it means "never", so it becomes null.
+//  3. EmitUnpopulated means absent repeated fields arrive as [] and absent messages as null; there is no
+//     way to distinguish "unset" from "empty", so every accessor tolerates both.
+
+/** Protobuf's zero timestamp. Headscale sends this for "never expires", "never seen", and friends. */
+const ZERO_TIME = '0001-01-01T00:00:00Z';
+
+/** An upstream timestamp as an ISO string, or null when it is unset/the protobuf zero value. */
+export function isoOrNull(raw: unknown): string | null {
+  if (typeof raw !== 'string' || !raw || raw === ZERO_TIME) return null;
+  const ms = Date.parse(raw);
+  if (Number.isNaN(ms)) return null;
+  // Some builds emit years far outside anything meaningful; treat pre-1971 as the sentinel too.
+  return ms < 31_536_000_000 ? null : new Date(ms).toISOString();
+}
+
+const str = (raw: unknown): string => (typeof raw === 'string' ? raw : '');
+const strArray = (raw: unknown): string[] =>
+  Array.isArray(raw) ? raw.filter((v): v is string => typeof v === 'string') : [];
+
+export type UpstreamUser = Record<string, unknown>;
+export type UpstreamNode = Record<string, unknown>;
+export type UpstreamPreAuthKey = Record<string, unknown>;
+
+export type OfficerUser = {
+  id: string;
+  name: string;
+  displayName: string | null;
+  email: string | null;
+  /** The OIDC provider, when the user came from one. Null for CLI/API-created users. */
+  provider: string | null;
+  profilePicUrl: string | null;
+  createdAt: string | null;
+};
+
+export function toUser(raw: UpstreamUser | null | undefined): OfficerUser | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const id = str(raw.id);
+  if (!id) return null;
+  return {
+    id,
+    name: str(raw.name),
+    displayName: str(raw.displayName) || null,
+    email: str(raw.email) || null,
+    provider: str(raw.provider) || null,
+    profilePicUrl: str(raw.profilePicUrl) || null,
+    createdAt: isoOrNull(raw.createdAt),
+  };
+}
+
+export type OfficerNode = {
+  id: string;
+  /** The name Headscale actually uses in the tailnet — givenName when set, otherwise the reported hostname. */
+  name: string;
+  hostname: string;
+  user: OfficerUser | null;
+  ipAddresses: string[];
+  online: boolean;
+  lastSeen: string | null;
+  /** When the node's key expires and it must re-authenticate. Null means it never expires. */
+  expiry: string | null;
+  createdAt: string | null;
+  /** How the node joined: 'authkey' | 'cli' | 'oidc' | 'unknown'. */
+  registerMethod: string;
+  tags: string[];
+  /** Routes the node advertises. */
+  availableRoutes: string[];
+  /** The subset the admin has approved — the writable one. */
+  approvedRoutes: string[];
+  /** Routes actually in effect (approved ∩ available, as Headscale computes it). */
+  subnetRoutes: string[];
+  /** True when the node advertises an exit node route. Purely derived, for the UI's badge. */
+  isExitNode: boolean;
+};
+
+const EXIT_ROUTES = new Set(['0.0.0.0/0', '::/0']);
+
+const REGISTER_METHODS: Record<string, string> = {
+  REGISTER_METHOD_AUTH_KEY: 'authkey',
+  REGISTER_METHOD_CLI: 'cli',
+  REGISTER_METHOD_OIDC: 'oidc',
+};
+
+export function toNode(raw: UpstreamNode): OfficerNode {
+  const givenName = str(raw.givenName);
+  const hostname = str(raw.name);
+  const availableRoutes = strArray(raw.availableRoutes);
+  return {
+    id: str(raw.id),
+    name: givenName || hostname,
+    hostname,
+    user: toUser(raw.user as UpstreamUser),
+    ipAddresses: strArray(raw.ipAddresses),
+    online: raw.online === true,
+    lastSeen: isoOrNull(raw.lastSeen),
+    expiry: isoOrNull(raw.expiry),
+    createdAt: isoOrNull(raw.createdAt),
+    registerMethod: REGISTER_METHODS[str(raw.registerMethod)] ?? 'unknown',
+    tags: strArray(raw.tags),
+    availableRoutes,
+    approvedRoutes: strArray(raw.approvedRoutes),
+    subnetRoutes: strArray(raw.subnetRoutes),
+    isExitNode: availableRoutes.some((r) => EXIT_ROUTES.has(r)),
+  };
+}
+
+export type OfficerPreAuthKey = {
+  id: string;
+  /**
+   * The usable secret. Non-null ONLY on the creation response — the list path nulls it unconditionally,
+   * so a secret can never reach the browser except at the moment it is created and must be shown once.
+   */
+  key: string | null;
+  /** A never-usable label for identifying a key in a list, e.g. `hskey-auth-a1b2c3-***`. */
+  keyDisplay: string;
+  user: OfficerUser | null;
+  reusable: boolean;
+  ephemeral: boolean;
+  used: boolean;
+  expiration: string | null;
+  createdAt: string | null;
+  aclTags: string[];
+  /** Derived lifecycle, so every surface agrees on what "spent" means. */
+  status: 'active' | 'used' | 'expired';
+};
+
+/**
+ * A display label that is never a usable secret.
+ *
+ * Headscale 0.28+ stores keys bcrypt-hashed and lists them already masked as `hskey-auth-<prefix>-***`.
+ * But keys created BEFORE 0.28 are still plaintext in its database, and `PreAuthKey.Proto()` returns those
+ * in full from the list endpoint "for backwards compatibility" — its own source carries a TODO about
+ * hiding them. So a list response on a server with history in it really does contain live secrets. We mask
+ * anything that isn't already masked rather than trusting the upstream to have done it.
+ */
+function displayLabel(key: string): string {
+  if (!key) return '(no key)';
+  if (key.endsWith('***')) return key;
+  return `${key.slice(0, 6)}…-***`;
+}
+
+type ToPreAuthKeyOptions = {
+  /**
+   * True only on the creation response, where the secret is the entire point and exists nowhere else.
+   * Everywhere else this is false and the secret is dropped before it can reach a cache or a browser.
+   */
+  reveal: boolean;
+};
+
+export function toPreAuthKey(raw: UpstreamPreAuthKey, { reveal }: ToPreAuthKeyOptions): OfficerPreAuthKey {
+  const expiration = isoOrNull(raw.expiration);
+  const reusable = raw.reusable === true;
+  const used = raw.used === true;
+  const key = str(raw.key);
+
+  // A reusable key stays usable after a node has claimed it, so `used` alone doesn't mean spent.
+  const expired = !!expiration && Date.parse(expiration) < Date.now();
+  const status: OfficerPreAuthKey['status'] = expired ? 'expired' : used && !reusable ? 'used' : 'active';
+
+  return {
+    id: str(raw.id),
+    key: reveal ? key || null : null,
+    keyDisplay: displayLabel(key),
+    user: toUser(raw.user as UpstreamUser),
+    reusable,
+    ephemeral: raw.ephemeral === true,
+    used,
+    expiration,
+    createdAt: isoOrNull(raw.createdAt),
+    aclTags: strArray(raw.aclTags),
+    status,
+  };
+}
+
+/** Read an array field out of a gateway response, tolerating the null/absent forms. */
+export function arrayField(body: unknown, field: string): Record<string, unknown>[] {
+  const value = (body as Record<string, unknown> | null)?.[field];
+  return Array.isArray(value) ? (value.filter((v) => v && typeof v === 'object') as Record<string, unknown>[]) : [];
+}

src/servers/sidecar/headscale/routes.ts

@@ -1,5 +1,8 @@
 import { HeadscaleError } from './client';
 import { handleServersRoute } from './servers';
+import { handleNodesRoute } from './nodes';
+import { handleUsersRoute } from './users';
+import { handleKeysRoute } from './keys';
 
 // Officer-owned routes for the headscale sidecar — the entire feature surface lives under /_officer/.
 //
@@ -17,6 +20,12 @@ export const notFound = (error = 'not found') => Response.json({ error }, { stat
 /** 405 when the path exists but the verb doesn't. */
 export const methodNotAllowed = () => Response.json({ error: 'method not allowed' }, { status: 405 });
 
+/** Parse a JSON request body, or null when there isn't one / it isn't an object. */
+export async function readJson(req: Request): Promise<Record<string, unknown> | null> {
+  const body = await req.json().catch(() => null);
+  return body && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>) : null;
+}
+
 /**
  * Dispatch an /_officer/* request. Returns null when nothing matches, which the caller turns into a 404.
  *
@@ -39,7 +48,13 @@ export async function handleOfficerRoute(req: Request, url: URL): Promise<Respon
     switch (segments[0]) {
       case 'servers':
         return await handleServersRoute(ctx, segments.slice(1));
-      // Domain routes (nodes, users, preauthkeys) land here, each operating against the active server.
+      // The domain routes below all act on the ACTIVE server — see active.ts for why that isn't a param.
+      case 'nodes':
+        return await handleNodesRoute(ctx, segments.slice(1));
+      case 'users':
+        return await handleUsersRoute(ctx, segments.slice(1));
+      case 'keys':
+        return await handleKeysRoute(ctx, segments.slice(1));
       default:
         return null;
     }

src/servers/sidecar/headscale/users.ts

@@ -0,0 +1,104 @@
+import type { OfficerContext } from './routes';
+import { badRequest, notFound, methodNotAllowed, readJson } from './routes';
+import { activeClient } from './active';
+import { toUser, toNode, arrayField, type OfficerUser } from './normalize';
+
+// User routes — /_officer/users/*. A Headscale "user" is a namespace that owns nodes and pre-auth keys.
+//
+// The list is enriched with a node count, which the admin API does not provide: deleting a user takes its
+// nodes with it, so "3 nodes" next to the delete button is the difference between an informed action and a
+// surprise. That is one extra upstream call for the whole list, not one per user.
+
+export type UserWithCounts = OfficerUser & { nodeCount: number; onlineCount: number };
+
+async function listUsers(ctx: OfficerContext): Promise<Response> {
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  const [userBody, nodeBody] = await Promise.all([client.call('/api/v1/user'), client.call('/api/v1/node')]);
+
+  const nodes = arrayField(nodeBody, 'nodes').map(toNode);
+  const counts = new Map<string, { total: number; online: number }>();
+  for (const node of nodes) {
+    const id = node.user?.id;
+    if (!id) continue;
+    const entry = counts.get(id) ?? { total: 0, online: 0 };
+    entry.total += 1;
+    if (node.online) entry.online += 1;
+    counts.set(id, entry);
+  }
+
+  const users: UserWithCounts[] = arrayField(userBody, 'users')
+    .map(toUser)
+    .filter((u): u is OfficerUser => !!u)
+    .map((u) => ({ ...u, nodeCount: counts.get(u.id)?.total ?? 0, onlineCount: counts.get(u.id)?.online ?? 0 }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return Response.json({ users });
+}
+
+async function createUser(ctx: OfficerContext): Promise<Response> {
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  const body = await readJson(ctx.req);
+  if (!body) return badRequest('expected a JSON body');
+  const name = typeof body.name === 'string' ? body.name.trim() : '';
+  if (!name) return badRequest('name is required');
+
+  const created = await client.call<{ user?: Record<string, unknown> }>('/api/v1/user', {
+    method: 'POST',
+    body: {
+      name,
+      displayName: typeof body.displayName === 'string' ? body.displayName.trim() : undefined,
+      email: typeof body.email === 'string' ? body.email.trim() : undefined,
+    },
+  });
+  return Response.json({ user: toUser(created.user) }, { status: 201 });
+}
+
+type UserActionParams = { ctx: OfficerContext; id: string; action: string | undefined };
+
+async function handleUserAction({ ctx, id, action }: UserActionParams): Promise<Response> {
+  const client = await activeClient(ctx.userId);
+  if (client instanceof Response) return client;
+
+  if (action === 'rename') {
+    if (ctx.req.method !== 'POST') return methodNotAllowed();
+    const body = await readJson(ctx.req);
+    if (!body) return badRequest('expected a JSON body');
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    if (!name) return badRequest('name is required');
+    // Rename takes both the id and the new name in the path — encode or a '/' becomes a routing accident.
+    const renamed = await client.call<{ user?: Record<string, unknown> }>(
+      `/api/v1/user/${encodeURIComponent(id)}/rename/${encodeURIComponent(name)}`,
+      { method: 'POST' },
+    );
+    return Response.json({ user: toUser(renamed.user) });
+  }
+
+  if (action !== undefined) return notFound();
+
+  if (ctx.req.method === 'DELETE') {
+    // Headscale refuses to delete a user that still owns nodes, with a message the UI relays verbatim.
+    await client.call(`/api/v1/user/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    return new Response(null, { status: 204 });
+  }
+
+  return methodNotAllowed();
+}
+
+/** Dispatch `/_officer/users/...`. `rest` is the path after `users`. */
+export async function handleUsersRoute(ctx: OfficerContext, rest: string[]): Promise<Response> {
+  if (rest.length === 0) {
+    if (ctx.req.method === 'GET') return listUsers(ctx);
+    if (ctx.req.method === 'POST') return createUser(ctx);
+    return methodNotAllowed();
+  }
+  if (rest.length > 2) return notFound();
+
+  const id = rest[0];
+  if (!id || !/^\d+$/.test(id)) return badRequest('user id must be numeric');
+
+  return handleUserAction({ ctx, id, action: rest[1] });
+}

src/servers/sidecar/headscale/version.ts

@@ -26,7 +26,10 @@ export type VersionProbe =
 
 /** `major.minor` from a Headscale version string, or null when it isn't semver (e.g. the literal 'dev'). */
 export function parseVersion(raw: string): { major: number; minor: number } | null {
-  const m = raw.trim().replace(/^v/, '').match(/^(\d+)\.(\d+)/);
+  const m = raw
+    .trim()
+    .replace(/^v/, '')
+    .match(/^(\d+)\.(\d+)/);
   if (!m) return null;
   return { major: Number(m[1]), minor: Number(m[2]) };
 }