feat: replace openapi hashing system with /version

Apparently I didn't use my brain cells and rely on the /version
endpoint that Headscale has exposed since 0.26 (our lowest supported
version). Switching to that significantly simplifies the API surface.

app/server/headscale/api/resources/api-keys.ts

@@ -0,0 +1,25 @@
+import type { Key } from "~/types";
+
+import type { Capabilities } from "../capabilities";
+import type { Transport } from "../transport";
+
+export interface ApiKeyApi {
+  list(): Promise<Key[]>;
+}
+
+export function makeApiKeyApi(
+  transport: Transport,
+  _capabilities: Capabilities,
+  apiKey: string,
+): ApiKeyApi {
+  return {
+    list: async () => {
+      const { apiKeys } = await transport.request<{ apiKeys: Key[] }>({
+        method: "GET",
+        path: "v1/apikey",
+        apiKey,
+      });
+      return apiKeys;
+    },
+  };
+}

app/server/headscale/api/resources/nodes.ts

@@ -0,0 +1,116 @@
+import type { Machine } from "~/types";
+
+import type { Capabilities } from "../capabilities";
+import type { Transport } from "../transport";
+
+interface RawMachine extends Omit<Machine, "tags"> {
+  tags?: string[];
+  forcedTags?: string[];
+  validTags?: string[];
+  invalidTags?: string[];
+}
+
+export interface NodeApi {
+  list(): Promise<Machine[]>;
+  get(id: string): Promise<Machine>;
+  delete(id: string): Promise<void>;
+  register(user: string, key: string): Promise<Machine>;
+  approveRoutes(id: string, routes: string[]): Promise<void>;
+  expire(id: string): Promise<void>;
+  rename(id: string, newName: string): Promise<void>;
+  setTags(id: string, tags: string[]): Promise<void>;
+  /**
+   * Reassign a node to a different user. Only present when
+   * `capabilities.nodeOwnerIsImmutable` is false (Headscale < 0.28).
+   */
+  reassignUser?: (id: string, user: string) => Promise<void>;
+}
+
+export function makeNodeApi(
+  transport: Transport,
+  capabilities: Capabilities,
+  apiKey: string,
+): NodeApi {
+  function normalize(raw: RawMachine): Machine {
+    if (capabilities.nodeTagsAreFlat) {
+      return { ...raw, tags: raw.tags ?? [] } as Machine;
+    }
+    const tags = Array.from(new Set([...(raw.forcedTags ?? []), ...(raw.validTags ?? [])]));
+    return { ...raw, tags } as Machine;
+  }
+
+  const api: NodeApi = {
+    list: async () => {
+      const { nodes } = await transport.request<{ nodes: RawMachine[] }>({
+        method: "GET",
+        path: "v1/node",
+        apiKey,
+      });
+      return nodes.map(normalize);
+    },
+    get: async (id) => {
+      const { node } = await transport.request<{ node: RawMachine }>({
+        method: "GET",
+        path: `v1/node/${id}`,
+        apiKey,
+      });
+      return normalize(node);
+    },
+    delete: async (id) => {
+      await transport.request({ method: "DELETE", path: `v1/node/${id}`, apiKey });
+    },
+    register: async (user, key) => {
+      // Headscale's node-register endpoint expects the registration
+      // params as both query string and body — preserved as-is.
+      const qp = new URLSearchParams();
+      qp.append("user", user);
+      qp.append("key", key);
+      const { node } = await transport.request<{ node: RawMachine }>({
+        method: "POST",
+        path: `v1/node/register?${qp.toString()}`,
+        apiKey,
+        body: { user, key },
+      });
+      return normalize(node);
+    },
+    approveRoutes: async (id, routes) => {
+      await transport.request({
+        method: "POST",
+        path: `v1/node/${id}/approve_routes`,
+        apiKey,
+        body: { routes },
+      });
+    },
+    expire: async (id) => {
+      await transport.request({ method: "POST", path: `v1/node/${id}/expire`, apiKey });
+    },
+    rename: async (id, newName) => {
+      await transport.request({
+        method: "POST",
+        path: `v1/node/${id}/rename/${encodeURIComponent(newName)}`,
+        apiKey,
+      });
+    },
+    setTags: async (id, tags) => {
+      await transport.request({
+        method: "POST",
+        path: `v1/node/${id}/tags`,
+        apiKey,
+        body: { tags },
+      });
+    },
+  };
+
+  if (!capabilities.nodeOwnerIsImmutable) {
+    api.reassignUser = async (id, user) => {
+      await transport.request({
+        method: "POST",
+        path: `v1/node/${id}/user`,
+        apiKey,
+        body: { user },
+      });
+    };
+  }
+
+  return api;
+}

app/server/headscale/api/resources/policy.ts

@@ -0,0 +1,33 @@
+import type { Capabilities } from "../capabilities";
+import type { Transport } from "../transport";
+
+export interface PolicyApi {
+  get(): Promise<{ policy: string; updatedAt: Date | null }>;
+  set(policy: string): Promise<{ policy: string; updatedAt: Date }>;
+}
+
+export function makePolicyApi(
+  transport: Transport,
+  _capabilities: Capabilities,
+  apiKey: string,
+): PolicyApi {
+  return {
+    get: async () => {
+      const { policy, updatedAt } = await transport.request<{
+        policy: string;
+        updatedAt: string;
+      }>({ method: "GET", path: "v1/policy", apiKey });
+      return {
+        policy,
+        updatedAt: updatedAt !== null ? new Date(updatedAt) : null,
+      };
+    },
+    set: async (policy) => {
+      const { policy: newPolicy, updatedAt } = await transport.request<{
+        policy: string;
+        updatedAt: string;
+      }>({ method: "PUT", path: "v1/policy", apiKey, body: { policy } });
+      return { policy: newPolicy, updatedAt: new Date(updatedAt) };
+    },
+  };
+}

app/server/headscale/api/resources/pre-auth-keys.ts

@@ -0,0 +1,88 @@
+import type { PreAuthKey } from "~/types";
+
+import type { Capabilities } from "../capabilities";
+import type { Transport } from "../transport";
+
+export interface CreatePreAuthKeyOptions {
+  /** Owning user ID, or `null` for tag-only keys (0.28+). */
+  user: string | null;
+  ephemeral: boolean;
+  reusable: boolean;
+  expiration: Date | null;
+  aclTags: string[] | null;
+}
+
+export interface PreAuthKeyApi {
+  /**
+   * List every pre-auth key on the server. Only present when
+   * `capabilities.preAuthKeysHaveStableIds` is true (Headscale 0.28+).
+   * Pre-0.28 callers must use {@link listForUser}.
+   */
+  listAll?: () => Promise<PreAuthKey[]>;
+
+  listForUser(userId: string): Promise<PreAuthKey[]>;
+
+  create(opts: CreatePreAuthKeyOptions): Promise<PreAuthKey>;
+
+  expire(key: PreAuthKey): Promise<void>;
+}
+
+export function makePreAuthKeyApi(
+  transport: Transport,
+  capabilities: Capabilities,
+  apiKey: string,
+): PreAuthKeyApi {
+  const api: PreAuthKeyApi = {
+    listForUser: async (userId) => {
+      const { preAuthKeys } = await transport.request<{
+        preAuthKeys: PreAuthKey[];
+      }>({ method: "GET", path: "v1/preauthkey", apiKey, query: { user: userId } });
+      return preAuthKeys;
+    },
+
+    create: async ({ user, ephemeral, reusable, expiration, aclTags }) => {
+      const body: Record<string, unknown> = {
+        ephemeral,
+        reusable,
+        expiration: expiration ? expiration.toISOString() : null,
+      };
+      if (user) body.user = user;
+      if (aclTags && aclTags.length > 0) body.aclTags = aclTags;
+
+      const { preAuthKey } = await transport.request<{
+        preAuthKey: PreAuthKey;
+      }>({ method: "POST", path: "v1/preauthkey", apiKey, body });
+      return preAuthKey;
+    },
+
+    expire: async (key) => {
+      if (capabilities.preAuthKeysHaveStableIds) {
+        await transport.request({
+          method: "POST",
+          path: "v1/preauthkey/expire",
+          apiKey,
+          body: { id: key.id },
+        });
+        return;
+      }
+      // Pre-0.28: expire takes user + key string.
+      await transport.request({
+        method: "POST",
+        path: "v1/preauthkey/expire",
+        apiKey,
+        body: { user: key.user?.name ?? "", key: key.key },
+      });
+    },
+  };
+
+  if (capabilities.preAuthKeysHaveStableIds) {
+    api.listAll = async () => {
+      const { preAuthKeys } = await transport.request<{
+        preAuthKeys: PreAuthKey[];
+      }>({ method: "GET", path: "v1/preauthkey", apiKey });
+      return preAuthKeys;
+    };
+  }
+
+  return api;
+}

app/server/headscale/api/resources/users.ts

@@ -0,0 +1,66 @@
+import type { User } from "~/types";
+
+import type { Capabilities } from "../capabilities";
+import type { Transport } from "../transport";
+
+export interface CreateUserOptions {
+  name: string;
+  email?: string;
+  displayName?: string;
+  pictureUrl?: string;
+}
+
+export interface ListUsersFilter {
+  id?: string;
+  name?: string;
+  email?: string;
+}
+
+export interface UserApi {
+  list(filter?: ListUsersFilter): Promise<User[]>;
+  create(opts: CreateUserOptions): Promise<User>;
+  delete(id: string): Promise<void>;
+  rename(id: string, newName: string): Promise<void>;
+}
+
+export function makeUserApi(
+  transport: Transport,
+  _capabilities: Capabilities,
+  apiKey: string,
+): UserApi {
+  return {
+    list: async (filter) => {
+      const { id, name, email } = filter ?? {};
+      const moreThanOneFilter = [id, name, email].filter((v) => v !== undefined).length > 1;
+      if (moreThanOneFilter) {
+        throw new Error("Only one of id, name, or email filters can be provided");
+      }
+      const { users } = await transport.request<{ users: User[] }>({
+        method: "GET",
+        path: "v1/user",
+        apiKey,
+        query: { id, name, email },
+      });
+      return users;
+    },
+    create: async ({ name, email, displayName, pictureUrl }) => {
+      const { user } = await transport.request<{ user: User }>({
+        method: "POST",
+        path: "v1/user",
+        apiKey,
+        body: { name, email, displayName, pictureUrl },
+      });
+      return user;
+    },
+    delete: async (id) => {
+      await transport.request({ method: "DELETE", path: `v1/user/${id}`, apiKey });
+    },
+    rename: async (id, newName) => {
+      await transport.request({
+        method: "POST",
+        path: `v1/user/${id}/rename/${encodeURIComponent(newName)}`,
+        apiKey,
+      });
+    },
+  };
+}