feat: add docker health check

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:nixos/nixpkgs/3edc4a3' (2025-12-27)
  → 'github:nixos/nixpkgs/3146c6a' (2026-01-10)

.github/ISSUE_TEMPLATE/bug-report.yaml

@@ -1,31 +1,31 @@
 name: Bug Report
 description: Report an issue with Headplane
 assignees: [tale]
-labels: [bug, triage]
+labels: ["Bug", "Needs Triage"]
 body:
-    - type: textarea
-      attributes:
-          label: Description
-          description: |
-              A detailed description of the issue and steps to reproduce it.
-              If applicable, include any error messages or screenshots.
+  - type: textarea
+    attributes:
+      label: Description
+      description: |
+        A detailed description of the issue and steps to reproduce it.
+        If applicable, include any error messages or screenshots.
 
-              If this is not an issue with Headplane, but an issue with your
-              environment, please consider opening a discussion instead.
-          placeholder: e.g. "When I try to upload a file, I get an error message."
-      validations:
-          required: true
-    - type: input
-      attributes:
-          label: Headplane Version
-          description: What version of Headplane are you using?
-          placeholder: e.g. "v0.5.5"
-      validations:
-          required: true
-    - type: input
-      attributes:
-          label: Headscale Version
-          description: What version of Headscale are you using?
-          placeholder: e.g. "v0.25.1"
-      validations:
-          required: true
+        If this is not an issue with Headplane, but an issue with your
+        environment, please consider opening a discussion instead.
+      placeholder: e.g. "When I try to upload a file, I get an error message."
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Headplane Version
+      description: What version of Headplane are you using?
+      placeholder: e.g. "v0.6.2"
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Headscale Version
+      description: What version of Headscale are you using?
+      placeholder: e.g. "v0.27.1"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature-request.yaml

@@ -1,15 +1,15 @@
 name: Feature Request
 description: Request a new feature or enhancement for Headplane
 assignees: [tale]
-labels: [enhancement, triage]
+labels: ["Feature", "Needs Triage"]
 body:
-    - type: textarea
-      attributes:
-          label: Description
-          description: |
-              A detailed description of the feature you would like to see added.
-              Please include any relevant context, such as why this feature is
-              important and how it would benefit other users beyond yourself.
-          placeholder: e.g. "I would like to see support for custom themes in Headplane so that I can personalize the interface to my liking."
-      validations:
-          required: true
+  - type: textarea
+    attributes:
+      label: Description
+      description: |
+        A detailed description of the feature you would like to see added.
+        Please include any relevant context, such as why this feature is
+        important and how it would benefit other users beyond yourself.
+      placeholder: e.g. "I would like to see support for custom themes in Headplane so that I can personalize the interface to my liking."
+    validations:
+      required: true

.github/workflows/build.yaml

@@ -2,14 +2,12 @@ name: Build
 on:
   push:
     paths-ignore:
-      - ".zed/**"
       - "assets/**"
       - "docs/**"
       - "CHANGELOG.md"
       - "README.md"
     branches:
       - "main"
-      - "next"
   pull_request:
 
 concurrency:
@@ -21,42 +19,38 @@ permissions:
   contents: read # Read access to the repository
 
 jobs:
-  native:
-    name: native
+  ci:
+    name: Build and Test
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repo
         uses: actions/checkout@v4
 
-      - name: Setup Mise
-        uses: jdx/mise-action@v2
-
-      - name: Set caching paths
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-          echo "GO_CACHE=$(go env GOCACHE)" >> $GITHUB_ENV
-          echo "GO_MODCACHE=$(go env GOMODCACHE)" >> $GITHUB_ENV
-
-      - uses: actions/cache@v4
-        name: Setup pnpm cache
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
         with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
+          run_install: false
 
-      - name: Setup Go cache
-        uses: actions/cache@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
         with:
-          path: |
-            ${{ env.GO_CACHE }}
-            ${{ env.GO_MODCACHE }}
-          key: ${{ runner.os }}-go-${{ hashFiles('**/go.mod', '**/go.sum') }}
+          node-version-file: package.json
+          cache: pnpm
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
 
       - name: CI pipeline
         run: ./build.sh --skip-pnpm-prune
 
+      - name: Run unit tests
+        run: pnpm run test:unit
+
+      - name: Run integration tests
+        run: pnpm run test:integration
+
   nix:
     name: nix
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -1,8 +1,30 @@
 # 0.6.2 (Next)
+- Added search and sortable columns to the machines list page (closes [#351](https://github.com/tale/headplane/issues/351)).
+- Added support for Headscale 0.27.0 and 0.27.1
 - Bundle all `node_modules` aside from native ones to reduce bundle and container size (closes [#331](https://github.com/tale/headplane/issues/331)).
 - Allow conditionally compiling the SSH WASM integration when building (closes [#337](https://github.com/tale/headplane/issues/337)).
 - Implemented the ability to customize the build with a custom script (see `./build.sh --help` for more information).
-
+- Attempt to warn against misconfigured cookie settings on the login page.
+- Made `server.cookie_max_age` and `server.cookie_domain` configurable (closes [#348](https://github.com/tale/headplane/issues/348)).
+- Re-worked the configuration loading system with several enhancements:
+    - It is now possible to skip a configuration file and only use environment variables (closes [#150](https://github.com/tale/headplane/issues/150)).
+    - Secret path loading has been reworked from the ground up to be more reliable (closes [#334](https://github.com/tale/headplane/issues/334)).
+    - Added better testing and validation for configuration loading
+- Re-worked the OIDC integration to adhere to the correct standards and surface more errors to the user.
+    - Deprecated `oidc.redirect_uri` and automated callback URL detection in favor of setting `server.base_url` correctly.
+    - Explicitly added `oidc.use_pkce` to correctly determine PKCE configuration.
+    - `oidc.token_endpoint_auth_method` is now optional and will attempt to be auto-detected, defaulting to `client_secret_basic` if unavailable (closes [#410](https://github.com/tale/headplane/issues/410)).
+- Removed several unnecessarily verbose or spammy log messages.
+- Updated the minimum Docker API used to support the latest Docker versions (via [#370](https://github.com/tale/headplane/pull/370)).
+- Enhanced the node tag dialog to show a dropdown of assignable tags (via [#362](https://github.com/tale/headplane/pull/362)).
+- Fixed an issue where the website favicon would not load correctly (closes [#323](https://github.com/tale/headplane/issues/323)).
+- Correctly handle invalid ACL policy inserts on Headscale 0.27+ (closes [#383](https://github.com/tale/headplane/issues/383)).
+- Prevent a machine from changing its owner to itself (closes [#373](https://github.com/tale/headplane/issues/373)).
+- Added an `/admin/api/info` route that can expose sensitive information if `server.info_secret` is set in the configuration (closes [#324](https://github.com/tale/headplane/issues/324)).
+- Correctly apply Gravatar profile pictures on the user page if applicable (closes [#405](https://github.com/tale/headplane/issues/405)).
+- Machine key registration no longer works if the key isn't 24 characters long (closes [#415](https://github.com/tale/headplane/issues/415)).
+- Fixed some mobile CSS issues across the application (closes [#401](https://github.com/tale/headplane/issues/401)).
+- Added a Docker healthcheck to the container (closes [#411](https://github.com/tale/headplane/issues/411)).
 ---
 
 # 0.6.1 (October 12, 2025)

Dockerfile

@@ -11,14 +11,16 @@ ARG TARGETOS
 ARG TARGETARCH
 ARG IMAGE_TAG
 RUN GOOS=$TARGETOS GOARCH=$TARGETARCH CGO_ENABLED=0 IMAGE_TAG=$IMAGE_TAG \
-	./build.sh --wasm --agent --fake-shell \
+	./build.sh --wasm --agent --fake-shell --healthcheck \
 		--wasm-output /bin/hp_ssh.wasm \
 		--agent-output /bin/hp_agent \
-		--fake-shell-output /bin/fake-sh
+		--fake-shell-output /bin/fake-sh \
+		--healthcheck-output /bin/hp_healthcheck
 
 RUN chmod +x /bin/hp_ssh.wasm
 RUN chmod +x /bin/hp_agent
 RUN chmod +x /bin/fake-sh
+RUN chmod +x /bin/hp_healthcheck
 
 # Folder needs to exist for later stages
 RUN mkdir -p /var/lib/headplane/agent
@@ -49,6 +51,10 @@ COPY --from=go-base /var/lib/headplane /var/lib/headplane
 COPY --from=go-base /bin/fake-sh /bin/sh
 COPY --from=go-base /bin/fake-sh /bin/bash
 
+COPY --from=go-base /bin/hp_healthcheck /bin/hp_healthcheck
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+	CMD ["/bin/hp_healthcheck"]
+
 WORKDIR /app
 CMD [ "/app/build/server/index.js" ]
 
@@ -61,6 +67,10 @@ COPY --from=js-base /run/node_modules /app/node_modules
 
 COPY --from=go-base /bin/hp_agent /usr/libexec/headplane/agent
 COPY --from=go-base /var/lib/headplane /var/lib/headplane
+COPY --from=go-base /bin/hp_healthcheck /bin/hp_healthcheck
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+	CMD ["/bin/hp_healthcheck"]
 
 WORKDIR /app
 CMD [ "node", "/app/build/server/index.js" ]

app/components/Code.tsx

@@ -5,7 +5,7 @@ import toast from '~/utils/toast';
 
 export interface CodeProps extends HTMLProps<HTMLSpanElement> {
 	isCopyable?: boolean;
-	children: string | string[];
+	children: string | string[] | number;
 }
 
 export default function Code({ isCopyable, children, className }: CodeProps) {

app/components/Dialog.tsx

@@ -107,6 +107,11 @@ function Panel(props: DialogPanelProps) {
 	return (
 		<Form
 			{...dialogProps}
+			className={cn(
+				'outline-hidden rounded-3xl w-full max-w-lg',
+				'bg-white dark:bg-headplane-900',
+			)}
+			method={method ?? 'POST'}
 			onSubmit={(event) => {
 				if (onSubmit) {
 					onSubmit(event);
@@ -114,12 +119,7 @@ function Panel(props: DialogPanelProps) {
 
 				close?.();
 			}}
-			method={method ?? 'POST'}
 			ref={ref}
-			className={cn(
-				'outline-hidden rounded-3xl w-full max-w-lg',
-				'bg-white dark:bg-headplane-900',
-			)}
 		>
 			<Card className="w-full max-w-lg" variant="flat">
 				{children}
@@ -130,9 +130,9 @@ function Panel(props: DialogPanelProps) {
 						<>
 							<Button onPress={close}>Cancel</Button>
 							<Button
+								isDisabled={isDisabled}
 								type="submit"
 								variant={variant === 'destructive' ? 'danger' : 'heavy'}
-								isDisabled={isDisabled}
 							>
 								Confirm
 							</Button>

app/components/Error.tsx

@@ -1,89 +0,0 @@
-import { AlertCircle } from 'lucide-react';
-import { isRouteErrorResponse, useRouteError } from 'react-router';
-import ResponseError from '~/server/headscale/api-error';
-import cn from '~/utils/cn';
-import Card from './Card';
-import Code from './Code';
-
-interface Props {
-	type?: 'full' | 'embedded';
-}
-
-export function getErrorMessage(error: Error | unknown): {
-	title: string;
-	message: string;
-} {
-	if (error instanceof ResponseError) {
-		if (error.responseObject?.message) {
-			return {
-				title: 'Headscale Error',
-				message: String(error.responseObject.message),
-			};
-		}
-
-		return {
-			title: 'Headscale Error',
-			message: error.response,
-		};
-	}
-
-	if (!(error instanceof Error)) {
-		return {
-			title: 'Unknown Error',
-			message: String(error),
-		};
-	}
-
-	let rootError = error;
-
-	// Traverse the error chain to find the root cause
-	if (error.cause) {
-		rootError = error.cause as Error;
-		while (rootError.cause) {
-			rootError = rootError.cause as Error;
-		}
-	}
-
-	// If we are aggregate, concat into a single message
-	if (rootError instanceof AggregateError) {
-		throw new Error('Unhandled AggregateError');
-	}
-
-	return {
-		title: 'Error',
-		message: rootError.message,
-	};
-}
-
-export function ErrorPopup({ type = 'full' }: Props) {
-	const error = useRouteError();
-	const routing = isRouteErrorResponse(error);
-	const { title, message } = getErrorMessage(error);
-
-	return (
-		<div
-			className={cn(
-				'flex items-center justify-center',
-				type === 'embedded'
-					? 'pointer-events-none mt-24'
-					: 'fixed inset-0 h-screen w-screen z-50',
-			)}
-		>
-			<Card>
-				<div className="flex items-center gap-4">
-					<AlertCircle className="w-8 h-8 text-red-500" />
-					<div className="flex justify-between items-center gap-2 w-full">
-						<Card.Title className="text-3xl mb-0">{title}</Card.Title>
-						{routing && <Code className="text-2xl">{`${error.status}`}</Code>}
-					</div>
-				</div>
-				<hr className="my-4 text-headplane-100 dark:text-headplane-800" />
-				<Card.Text
-					className={cn('py-4 text-lg', routing ? 'font-normal' : 'font-mono')}
-				>
-					{routing ? error.data : message}
-				</Card.Text>
-			</Card>
-		</div>
-	);
-}

app/components/Input.tsx

@@ -8,11 +8,18 @@ export interface InputProps extends AriaTextFieldProps<HTMLInputElement> {
 	labelHidden?: boolean;
 	isRequired?: boolean;
 	className?: string;
+	isInvalid?: boolean;
+	errorMessage?: string;
 }
 
-// TODO: Custom isInvalid logic for custom error messages
 export default function Input(props: InputProps) {
-	const { label, labelHidden, className } = props;
+	const {
+		label,
+		labelHidden,
+		className,
+		isInvalid: customIsInvalid,
+		errorMessage,
+	} = props;
 	const ref = useRef<HTMLInputElement | null>(null);
 	const id = useId(props.id);
 
@@ -21,7 +28,7 @@ export default function Input(props: InputProps) {
 		inputProps,
 		descriptionProps,
 		errorMessageProps,
-		isInvalid,
+		isInvalid: ariaIsInvalid,
 		validationErrors,
 	} = useTextField(
 		{
@@ -32,16 +39,18 @@ export default function Input(props: InputProps) {
 		ref,
 	);
 
+	const isInvalid = customIsInvalid ?? ariaIsInvalid;
+
 	return (
-		<div className="flex flex-col w-full" aria-label={label}>
+		<div className="flex flex-col w-full">
 			<label
 				{...labelProps}
-				htmlFor={id}
 				className={cn(
 					'text-xs font-medium px-3 mb-0.5',
 					'text-headplane-700 dark:text-headplane-100',
 					labelHidden && 'sr-only',
 				)}
+				htmlFor={id}
 			>
 				{label}
 				{props.isRequired && (
@@ -50,8 +59,6 @@ export default function Input(props: InputProps) {
 			</label>
 			<input
 				{...inputProps}
-				required={props.isRequired}
-				ref={ref}
 				className={cn(
 					'rounded-xl px-3 py-2',
 					'focus:outline-hidden focus:ring-3',
@@ -59,6 +66,8 @@ export default function Input(props: InputProps) {
 					'border border-headplane-100 dark:border-headplane-800',
 					className,
 				)}
+				ref={ref}
+				required={props.isRequired}
 			/>
 			{props.description && (
 				<div
@@ -76,7 +85,7 @@ export default function Input(props: InputProps) {
 					{...errorMessageProps}
 					className={cn('text-xs px-3 mt-1', 'text-red-500 dark:text-red-400')}
 				>
-					{validationErrors.join(' ')}
+					{errorMessage ?? validationErrors.join(' ')}
 				</div>
 			) : null}
 		</div>

app/components/Select.tsx

@@ -50,11 +50,11 @@ function Select(props: SelectProps) {
 		<div className={cn('flex flex-col', props.className)}>
 			<label
 				{...labelProps}
-				htmlFor={id}
 				className={cn(
 					'text-xs font-medium px-3 mb-0.5',
 					'text-headplane-700 dark:text-headplane-100',
 				)}
+				htmlFor={id}
 			>
 				{props.label}
 			</label>
@@ -63,18 +63,18 @@ function Select(props: SelectProps) {
 					'flex rounded-xl focus:outline-hidden focus-within:ring-3',
 					'bg-white dark:bg-headplane-900',
 					'border border-headplane-100 dark:border-headplane-800',
+					props.isInvalid && 'ring-red-400',
 				)}
 			>
 				<input
 					{...inputProps}
-					ref={inputRef}
-					id={id}
 					className="outline-hidden px-3 py-2 rounded-l-xl w-full bg-transparent"
 					data-1p-ignore
+					id={id}
+					ref={inputRef}
 				/>
 				<button
 					{...buttonProps}
-					ref={buttonRef}
 					className={cn(
 						'flex items-center justify-center p-1 rounded-lg m-1',
 						'bg-headplane-100 dark:bg-headplane-700/30 font-medium',
@@ -82,6 +82,7 @@ function Select(props: SelectProps) {
 							? 'opacity-50 cursor-not-allowed'
 							: 'hover:bg-headplane-200/90 dark:hover:bg-headplane-800/30',
 					)}
+					ref={buttonRef}
 				>
 					<ChevronDown className="p-0.5" />
 				</button>
@@ -99,12 +100,12 @@ function Select(props: SelectProps) {
 			)}
 			{state.isOpen && (
 				<Popover
-					popoverRef={popoverRef}
-					triggerRef={inputRef}
-					state={state}
+					className="w-full max-w-xs"
 					isNonModal
 					placement="bottom start"
-					className="w-full max-w-xs"
+					popoverRef={popoverRef}
+					state={state}
+					triggerRef={inputRef}
 				>
 					<ListBox {...listBoxProps} listBoxRef={listBoxRef} state={state} />
 				</Popover>
@@ -114,23 +115,22 @@ function Select(props: SelectProps) {
 }
 
 interface ListBoxProps extends AriaListBoxOptions<object> {
-	listBoxRef?: React.RefObject<HTMLUListElement | null>;
+	listBoxRef: React.RefObject<HTMLUListElement | null>;
 	state: ListState<object>;
 }
 
 function ListBox(props: ListBoxProps) {
 	const { listBoxRef, state } = props;
-	const ref = listBoxRef ?? useRef<HTMLUListElement | null>(null);
-	const { listBoxProps } = useListBox(props, state, ref);
+	const { listBoxProps } = useListBox(props, state, listBoxRef);
 
 	return (
 		<ul
 			{...listBoxProps}
-			ref={listBoxRef}
 			className="w-full max-h-72 overflow-auto outline-hidden pt-1"
+			ref={listBoxRef}
 		>
 			{[...state.collection].map((item) => (
-				<Option key={item.key} item={item} state={state} />
+				<Option item={item} key={item.key} state={state} />
 			))}
 		</ul>
 	);
@@ -154,7 +154,6 @@ function Option({ item, state }: OptionProps) {
 	return (
 		<li
 			{...optionProps}
-			ref={ref}
 			className={cn(
 				'flex items-center justify-between',
 				'py-2 px-3 mx-1 rounded-lg mb-1',
@@ -164,6 +163,7 @@ function Option({ item, state }: OptionProps) {
 					: 'hover:bg-headplane-100/50 dark:hover:bg-headplane-800',
 				isDisabled && 'text-headplane-300 dark:text-headplane-600',
 			)}
+			ref={ref}
 		>
 			{item.rendered}
 			{isSelected && <Check className="p-0.5" />}

app/components/Tabs.tsx

@@ -23,15 +23,15 @@ function Tabs({ label, className, ...props }: TabsProps) {
 		<div className={cn('flex flex-col', className)}>
 			<div
 				{...tabListProps}
-				ref={ref}
 				className={cn(
-					'flex items-center rounded-t-xl w-fit',
+					'flex items-center rounded-t-xl w-fit max-w-full overflow-x-auto',
 					'border-headplane-100 dark:border-headplane-800',
 					'border-t border-x',
 				)}
+				ref={ref}
 			>
 				{[...state.collection].map((item) => (
-					<Tab key={item.key} item={item} state={state} />
+					<Tab item={item} key={item.key} state={state} />
 				))}
 			</div>
 			<TabsPanel key={state.selectedItem?.key} state={state} />
@@ -52,7 +52,6 @@ function Tab({ item, state }: TabsTabProps) {
 	return (
 		<div
 			{...tabProps}
-			ref={ref}
 			className={cn(
 				'pl-2 pr-3 py-2.5',
 				'aria-selected:bg-headplane-100 dark:aria-selected:bg-headplane-950',
@@ -60,6 +59,7 @@ function Tab({ item, state }: TabsTabProps) {
 				'border-r border-headplane-100 dark:border-headplane-800',
 				'first:rounded-tl-xl last:rounded-tr-xl last:border-r-0',
 			)}
+			ref={ref}
 		>
 			{rendered}
 		</div>
@@ -76,11 +76,11 @@ function TabsPanel({ state, ...props }: TabsPanelProps) {
 	return (
 		<div
 			{...tabPanelProps}
-			ref={ref}
 			className={cn(
 				'w-full overflow-clip rounded-b-xl rounded-r-xl',
 				'border border-headplane-100 dark:border-headplane-800',
 			)}
+			ref={ref}
 		>
 			{state.selectedItem?.props.children}
 		</div>

app/components/error-banner.tsx

@@ -0,0 +1,211 @@
+import { AlertCircle } from 'lucide-react';
+import { isRouteErrorResponse } from 'react-router';
+import {
+	isApiError,
+	isConnectionError,
+} from '~/server/headscale/api/error-client';
+import cn from '~/utils/cn';
+import Card from './Card';
+import Code from './Code';
+import Link from './Link';
+
+export function getErrorMessage(error: Error | unknown): {
+	title: string;
+	jsxMessage: React.ReactNode;
+} {
+	if (isRouteErrorResponse(error)) {
+		if (isApiError(error.data)) {
+			const { statusCode, rawData, data, requestUrl } = error.data;
+			if (statusCode >= 500) {
+				return {
+					title: 'Headscale API Error',
+					jsxMessage: (
+						<>
+							<Card.Text>
+								There was an error communicating with the Headscale API.
+								<br />
+								The server responded with a status code of{' '}
+								<strong>{statusCode}</strong>, indicating a server-side issue.
+								Please check the Headscale server status and try again later.
+							</Card.Text>
+							{(error.data.data != null || error.data.rawData != null) && (
+								<pre className="mt-2 p-2 bg-headplane-100 dark:bg-headplane-800 rounded-lg overflow-x-auto">
+									{error.data.data != null ? (
+										<code>{JSON.stringify(error.data.data, null, 2)}</code>
+									) : (
+										<code>{error.data.rawData}</code>
+									)}
+								</pre>
+							)}
+						</>
+					),
+				};
+			}
+
+			const authError =
+				error.data.statusCode === 401 || error.data.statusCode === 403;
+
+			return {
+				title: 'Invalid response from Headscale API',
+				jsxMessage: (
+					<>
+						<Card.Text className="leading-snug">
+							The Headscale API returned an unexpected response.
+							{authError ? (
+								<>
+									{' '}
+									The status code indicates an authentication error. Please
+									verify your API key and Headplane configuration.
+								</>
+							) : (
+								<>
+									{' '}
+									You may be using an unsupported version of Headscale or this
+									may be a bug.
+								</>
+							)}
+						</Card.Text>
+						<ul className="list-disc list-inside mt-2">
+							<li>
+								Request URL: <Code>{requestUrl}</Code>
+							</li>
+							<li>
+								Status Code:{' '}
+								<Code>
+									{/* @ts-expect-error */}
+									{data === null ? (
+										<>
+											{statusCode} {rawData}
+										</>
+									) : (
+										<>
+											{statusCode} {error.statusText}
+										</>
+									)}
+								</Code>
+							</li>
+						</ul>
+						<Card.Text className="text-lg font-semibold mt-4">
+							Error Details
+						</Card.Text>
+						<pre className="mt-2 p-2 bg-headplane-100 dark:bg-headplane-800 rounded-lg overflow-x-auto">
+							<code>{JSON.stringify(error.data, null, 2)}</code>
+						</pre>
+					</>
+				),
+			};
+		}
+
+		if (isConnectionError(error.data)) {
+			const { requestUrl, errorCode, errorMessage, extraData } = error.data;
+			return {
+				title: 'Cannot connect to Headscale API',
+				jsxMessage: (
+					<>
+						<Card.Text className="leading-snug">
+							Headplane was unable to reach the Headscale API. Please check your
+							network setup and configuration to ensure Headplane is able to
+							connect.
+						</Card.Text>
+						<Card.Text className="text-lg font-semibold mt-4">
+							Error Details
+						</Card.Text>
+						<pre className="mt-2 p-2 bg-headplane-100 dark:bg-headplane-800 rounded-lg overflow-x-auto">
+							{requestUrl}
+							<br />
+							{errorCode}: {errorMessage}
+							{extraData != null && (
+								<>
+									<br />
+									<br />
+									<code>{JSON.stringify(extraData, null, 2)}</code>
+								</>
+							)}
+						</pre>
+					</>
+				),
+			};
+		}
+
+		return {
+			title: `Error ${error.status}`,
+			jsxMessage: (
+				<>
+					There was an error processing your request.
+					<br />
+					Status Code: <strong>{error.status}</strong>
+					<br />
+					Status Text: <strong>{error.data}</strong>
+				</>
+			),
+		};
+	}
+
+	if (!(error instanceof Error)) {
+		return {
+			title: 'Unexpected Error',
+			jsxMessage: (
+				<>
+					<Card.Text>
+						An unexpected error occurred which is most likely a bug. Please
+						consider reporting filing an issue on the{' '}
+						<Link
+							name="Headplane GitHub"
+							to="https://github.com/tale/headplane/issues"
+						>
+							Headplane GitHub
+						</Link>{' '}
+						repository with the details below.
+					</Card.Text>
+					<Card.Text className="text-lg font-semibold mt-4">
+						Error Details
+					</Card.Text>
+					<pre className="mt-2 p-2 bg-headplane-100 dark:bg-headplane-800 rounded-lg overflow-x-auto">
+						<code>{JSON.stringify(error, null, 2)}</code>
+					</pre>
+				</>
+			),
+		};
+	}
+
+	// Traverse the error chain to find the root cause
+	let rootError = error;
+	if (error.cause != null) {
+		rootError = error.cause as Error;
+		while (rootError.cause != null) {
+			rootError = rootError.cause as Error;
+		}
+	}
+
+	// TODO: If we are aggregate, concat into a single message
+	if (rootError instanceof AggregateError) {
+		throw new Error('AggregateError handling not implemented yet');
+	}
+
+	return {
+		title:
+			rootError.name.length > 0 && rootError.name !== 'Error'
+				? `Error: ${rootError.name}`
+				: 'Error',
+		jsxMessage: rootError.message,
+	};
+}
+
+interface ErrorBannerProps {
+	error: unknown;
+	className?: string;
+}
+
+export function ErrorBanner({ error, className }: ErrorBannerProps) {
+	const { title, jsxMessage } = getErrorMessage(error);
+
+	return (
+		<Card className={cn('w-screen', className)} variant="flat">
+			<div className="flex items-center justify-between gap-4">
+				<Card.Title>{title}</Card.Title>
+				<AlertCircle className="w-6 h-6 mb-2 text-red-500" />
+			</div>
+			{jsxMessage}
+		</Card>
+	);
+}

app/entry.client.tsx

@@ -2,12 +2,6 @@ import { StrictMode, startTransition } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { HydratedRouter } from 'react-router/dom';
 
-if (import.meta.env.DEV) {
-	import('react-scan').then(({ scan }) => {
-		scan({ enabled: true });
-	});
-}
-
 startTransition(() => {
 	hydrateRoot(
 		document,

app/entry.server.tsx

@@ -3,7 +3,8 @@ import { createReadableStreamFromReadable } from '@react-router/node';
 import { isbot } from 'isbot';
 import type { RenderToPipeableStreamOptions } from 'react-dom/server';
 import { renderToPipeableStream } from 'react-dom/server';
-import { AppLoadContext, EntryContext, ServerRouter } from 'react-router';
+import type { AppLoadContext, EntryContext } from 'react-router';
+import { ServerRouter } from 'react-router';
 
 export const streamTimeout = 5_000;
 export default function handleRequest(

app/layouts/dashboard.tsx

@@ -1,27 +1,27 @@
-import { type LoaderFunctionArgs, Outlet, redirect } from 'react-router';
-import { ErrorPopup } from '~/components/Error';
-import type { LoadContext } from '~/server';
+import { Outlet, redirect } from 'react-router';
+import { ErrorBanner } from '~/components/error-banner';
 import { pruneEphemeralNodes } from '~/server/db/pruner';
-import ResponseError from '~/server/headscale/api-error';
+import { isDataUnauthorizedError } from '~/server/headscale/api/error-client';
 import log from '~/utils/log';
+import type { Route } from './+types/dashboard';
 
-export async function loader({
-	request,
-	context,
-	...rest
-}: LoaderFunctionArgs<LoadContext>) {
-	const healthy = await context.client.healthcheck();
+export async function loader({ request, context, ...rest }: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
-	await pruneEphemeralNodes({ context, request, ...rest });
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 
-	// We shouldn't session invalidate if Headscale is down
-	// TODO: Notify in the logs or the UI that OIDC auth key is wrong if enabled
+	// MARK: The session should stay valid if Headscale isn't healthy
+	const healthy = await api.isHealthy();
 	if (healthy) {
 		try {
-			await context.client.get('v1/apikey', session.api_key);
+			await api.getApiKeys();
+			await pruneEphemeralNodes({ context, request, ...rest });
 		} catch (error) {
-			if (error instanceof ResponseError) {
-				log.debug('api', 'API Key validation failed %o', error);
+			if (isDataUnauthorizedError(error)) {
+				log.warn(
+					'auth',
+					'Logging out %s due to expired API key',
+					session.user.name,
+				);
 				return redirect('/login', {
 					headers: {
 						'Set-Cookie': await context.sessions.destroySession(),
@@ -44,6 +44,10 @@ export default function Layout() {
 	);
 }
 
-export function ErrorBoundary() {
-	return <ErrorPopup type="embedded" />;
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+	return (
+		<div className="w-fit mx-auto overscroll-contain my-24">
+			<ErrorBanner className="max-w-2xl" error={error} />
+		</div>
+	);
 }

app/layouts/shell.tsx

@@ -1,30 +1,22 @@
 import { eq } from 'drizzle-orm';
 import { CircleCheckIcon } from 'lucide-react';
-import {
-	LoaderFunctionArgs,
-	Outlet,
-	redirect,
-	useLoaderData,
-} from 'react-router';
+import { Outlet, redirect } from 'react-router';
 import Button from '~/components/Button';
 import Card from '~/components/Card';
 import Footer from '~/components/Footer';
 import Header from '~/components/Header';
-import type { LoadContext } from '~/server';
 import { users } from '~/server/db/schema';
 import { Capabilities } from '~/server/web/roles';
 import toast from '~/utils/toast';
+import { Route } from './+types/shell';
 
 // This loads the bare minimum for the application to function
 // So we know that if context fails to load then well, oops?
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	try {
 		const session = await context.sessions.auth(request);
 		if (
-			context.oidc &&
+			typeof context.oidc === 'object' &&
 			session.user.subject !== 'unknown-non-oauth' &&
 			!request.url.endsWith('/onboarding')
 		) {
@@ -39,6 +31,7 @@ export async function loader({
 			}
 		}
 
+		const api = context.hsApi.getRuntimeClient(session.api_key);
 		const check = await context.sessions.check(request, Capabilities.ui_access);
 		return {
 			config: context.hs.c,
@@ -62,7 +55,7 @@ export async function loader({
 				),
 			},
 			onboarding: request.url.endsWith('/onboarding'),
-			healthy: await context.client.healthcheck(),
+			healthy: await api.isHealthy(),
 		};
 	} catch {
 		return redirect('/login', {
@@ -73,14 +66,12 @@ export async function loader({
 	}
 }
 
-export default function Shell() {
-	const data = useLoaderData<typeof loader>();
-
+export default function Shell({ loaderData }: Route.ComponentProps) {
 	return (
 		<>
-			<Header {...data} />
+			<Header {...loaderData} />
 			{/* Always show the outlet if we are onboarding */}
-			{(data.onboarding ? true : data.uiAccess) ? (
+			{(loaderData.onboarding ? true : loaderData.uiAccess) ? (
 				<Outlet />
 			) : (
 				<Card className="mx-auto w-fit mt-24">
@@ -96,13 +87,13 @@ export default function Shell() {
 						className="flex text-md font-mono"
 						onPress={async () => {
 							await navigator.clipboard.writeText(
-								`tailscale up --login-server=${data.url}`,
+								`tailscale up --login-server=${loaderData.url}`,
 							);
 
 							toast('Copied to clipboard');
 						}}
 					>
-						tailscale up --login-server={data.url}
+						tailscale up --login-server={loaderData.url}
 					</Button>
 					<p className="text-xs mt-1 opacity-50 text-center">
 						Click this button to copy the command.
@@ -113,7 +104,7 @@ export default function Shell() {
 					</p>
 				</Card>
 			)}
-			<Footer {...data} />
+			<Footer {...loaderData} />
 		</>
 	);
 }

app/openapi-canonical-families.json

@@ -0,0 +1,5 @@
+{
+	"0.26.1": ["0.26.0", "0.26.1"],
+	"0.27.0": ["0.27.0"],
+	"0.27.1": ["0.27.1"]
+}

app/openapi-operation-hashes.json

@@ -0,0 +1,108 @@
+{
+	"0.26.0": {
+		"GET /api/v1/apikey": "efe31b6dc980e158",
+		"POST /api/v1/apikey": "39953a96c1da5312",
+		"POST /api/v1/apikey/expire": "ca56add866802f17",
+		"DELETE /api/v1/apikey/{prefix}": "3f0125f7abe7abb1",
+		"POST /api/v1/debug/node": "204f9ae3f9f738c6",
+		"GET /api/v1/node": "8bb18b8c7cfb4f20",
+		"POST /api/v1/node/backfillips": "6da4d1d3922a8001",
+		"POST /api/v1/node/register": "539f7cb3a84d43d4",
+		"GET /api/v1/node/{nodeId}": "8a7da3d24dc82c37",
+		"DELETE /api/v1/node/{nodeId}": "f832f33d84fd3724",
+		"POST /api/v1/node/{nodeId}/approve_routes": "e6c22e46ad44903d",
+		"POST /api/v1/node/{nodeId}/expire": "ac9ffcd6243a9784",
+		"POST /api/v1/node/{nodeId}/rename/{newName}": "d355388ac934dc90",
+		"POST /api/v1/node/{nodeId}/tags": "b6a8296dcc2939b5",
+		"POST /api/v1/node/{nodeId}/user": "ae3a30b43ffd1922",
+		"GET /api/v1/policy": "d6c639be304cd3c0",
+		"PUT /api/v1/policy": "6cbe80bde771a388",
+		"GET /api/v1/preauthkey": "14db6a04f90d7a7e",
+		"POST /api/v1/preauthkey": "0b4308e049d4eb58",
+		"POST /api/v1/preauthkey/expire": "31f377a66d3a5c4f",
+		"GET /api/v1/user": "228831b58ccc5a17",
+		"POST /api/v1/user": "a4e1d889d7962da5",
+		"DELETE /api/v1/user/{id}": "3d553e4b74296884",
+		"POST /api/v1/user/{oldId}/rename/{newName}": "996c03ebf81576d7"
+	},
+	"0.26.1": {
+		"GET /api/v1/apikey": "efe31b6dc980e158",
+		"POST /api/v1/apikey": "39953a96c1da5312",
+		"POST /api/v1/apikey/expire": "ca56add866802f17",
+		"DELETE /api/v1/apikey/{prefix}": "3f0125f7abe7abb1",
+		"POST /api/v1/debug/node": "204f9ae3f9f738c6",
+		"GET /api/v1/node": "8bb18b8c7cfb4f20",
+		"POST /api/v1/node/backfillips": "6da4d1d3922a8001",
+		"POST /api/v1/node/register": "539f7cb3a84d43d4",
+		"GET /api/v1/node/{nodeId}": "8a7da3d24dc82c37",
+		"DELETE /api/v1/node/{nodeId}": "f832f33d84fd3724",
+		"POST /api/v1/node/{nodeId}/approve_routes": "e6c22e46ad44903d",
+		"POST /api/v1/node/{nodeId}/expire": "ac9ffcd6243a9784",
+		"POST /api/v1/node/{nodeId}/rename/{newName}": "d355388ac934dc90",
+		"POST /api/v1/node/{nodeId}/tags": "b6a8296dcc2939b5",
+		"POST /api/v1/node/{nodeId}/user": "ae3a30b43ffd1922",
+		"GET /api/v1/policy": "d6c639be304cd3c0",
+		"PUT /api/v1/policy": "6cbe80bde771a388",
+		"GET /api/v1/preauthkey": "14db6a04f90d7a7e",
+		"POST /api/v1/preauthkey": "0b4308e049d4eb58",
+		"POST /api/v1/preauthkey/expire": "31f377a66d3a5c4f",
+		"GET /api/v1/user": "228831b58ccc5a17",
+		"POST /api/v1/user": "a4e1d889d7962da5",
+		"DELETE /api/v1/user/{id}": "3d553e4b74296884",
+		"POST /api/v1/user/{oldId}/rename/{newName}": "996c03ebf81576d7"
+	},
+	"0.27.0": {
+		"GET /api/v1/apikey": "efe31b6dc980e158",
+		"POST /api/v1/apikey": "39953a96c1da5312",
+		"POST /api/v1/apikey/expire": "ca56add866802f17",
+		"DELETE /api/v1/apikey/{prefix}": "3f0125f7abe7abb1",
+		"POST /api/v1/debug/node": "204f9ae3f9f738c6",
+		"GET /api/v1/health": "5e447272e72b2e5f",
+		"GET /api/v1/node": "8bb18b8c7cfb4f20",
+		"POST /api/v1/node/backfillips": "6da4d1d3922a8001",
+		"POST /api/v1/node/register": "539f7cb3a84d43d4",
+		"GET /api/v1/node/{nodeId}": "8a7da3d24dc82c37",
+		"DELETE /api/v1/node/{nodeId}": "f832f33d84fd3724",
+		"POST /api/v1/node/{nodeId}/approve_routes": "e6c22e46ad44903d",
+		"POST /api/v1/node/{nodeId}/expire": "ac9ffcd6243a9784",
+		"POST /api/v1/node/{nodeId}/rename/{newName}": "d355388ac934dc90",
+		"POST /api/v1/node/{nodeId}/tags": "b6a8296dcc2939b5",
+		"POST /api/v1/node/{nodeId}/user": "ae3a30b43ffd1922",
+		"GET /api/v1/policy": "d6c639be304cd3c0",
+		"PUT /api/v1/policy": "6cbe80bde771a388",
+		"GET /api/v1/preauthkey": "14db6a04f90d7a7e",
+		"POST /api/v1/preauthkey": "0b4308e049d4eb58",
+		"POST /api/v1/preauthkey/expire": "31f377a66d3a5c4f",
+		"GET /api/v1/user": "228831b58ccc5a17",
+		"POST /api/v1/user": "a4e1d889d7962da5",
+		"DELETE /api/v1/user/{id}": "3d553e4b74296884",
+		"POST /api/v1/user/{oldId}/rename/{newName}": "996c03ebf81576d7"
+	},
+	"0.27.1": {
+		"GET /api/v1/apikey": "efe31b6dc980e158",
+		"POST /api/v1/apikey": "39953a96c1da5312",
+		"POST /api/v1/apikey/expire": "ca56add866802f17",
+		"DELETE /api/v1/apikey/{prefix}": "3f0125f7abe7abb1",
+		"POST /api/v1/debug/node": "204f9ae3f9f738c6",
+		"GET /api/v1/health": "5e447272e72b2e5f",
+		"GET /api/v1/node": "8bb18b8c7cfb4f20",
+		"POST /api/v1/node/backfillips": "6da4d1d3922a8001",
+		"POST /api/v1/node/register": "539f7cb3a84d43d4",
+		"GET /api/v1/node/{nodeId}": "8a7da3d24dc82c37",
+		"DELETE /api/v1/node/{nodeId}": "f832f33d84fd3724",
+		"POST /api/v1/node/{nodeId}/approve_routes": "e6c22e46ad44903d",
+		"POST /api/v1/node/{nodeId}/expire": "53efc8e2017c16ae",
+		"POST /api/v1/node/{nodeId}/rename/{newName}": "d355388ac934dc90",
+		"POST /api/v1/node/{nodeId}/tags": "b6a8296dcc2939b5",
+		"POST /api/v1/node/{nodeId}/user": "ae3a30b43ffd1922",
+		"GET /api/v1/policy": "d6c639be304cd3c0",
+		"PUT /api/v1/policy": "6cbe80bde771a388",
+		"GET /api/v1/preauthkey": "14db6a04f90d7a7e",
+		"POST /api/v1/preauthkey": "0b4308e049d4eb58",
+		"POST /api/v1/preauthkey/expire": "31f377a66d3a5c4f",
+		"GET /api/v1/user": "228831b58ccc5a17",
+		"POST /api/v1/user": "a4e1d889d7962da5",
+		"DELETE /api/v1/user/{id}": "3d553e4b74296884",
+		"POST /api/v1/user/{oldId}/rename/{newName}": "996c03ebf81576d7"
+	}
+}

app/root.tsx

@@ -9,12 +9,13 @@ import {
 } from 'react-router';
 import '@fontsource-variable/inter';
 import { ExternalScripts } from 'remix-utils/external-scripts';
-import { ErrorPopup } from '~/components/Error';
 import ProgressBar from '~/components/ProgressBar';
 import ToastProvider from '~/components/ToastProvider';
 import stylesheet from '~/tailwind.css?url';
 import { LiveDataProvider } from '~/utils/live-data';
 import { useToastQueue } from '~/utils/toast';
+import type { Route } from './+types/root';
+import { ErrorBanner } from './components/error-banner';
 
 export const meta: MetaFunction = () => [
 	{ title: 'Headplane' },
@@ -44,7 +45,7 @@ export function Layout({ children }: { readonly children: React.ReactNode }) {
 					<Links />
 					<link href="favicon.ico" rel="icon" />
 				</head>
-				<body className="overscroll-none dark:bg-headplane-900 dark:text-headplane-50">
+				<body className="overscroll-none overflow-x-hidden dark:bg-headplane-900 dark:text-headplane-50">
 					{children}
 					<ToastProvider queue={toastQueue} />
 					<ScrollRestoration />
@@ -56,8 +57,12 @@ export function Layout({ children }: { readonly children: React.ReactNode }) {
 	);
 }
 
-export function ErrorBoundary() {
-	return <ErrorPopup />;
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+	return (
+		<div className="w-screen h-screen flex items-center justify-center p-4">
+			<ErrorBanner className="max-w-2xl" error={error} />
+		</div>
+	);
 }
 
 export default function App() {

app/routes.ts

@@ -5,6 +5,9 @@ export default [
 	index('routes/util/redirect.ts'),
 	route('/healthz', 'routes/util/healthz.ts'),
 
+	// API Routes
+	...prefix('/api', [route('/info', 'routes/util/info.ts')]),
+
 	// Authentication Routes
 	route('/login', 'routes/auth/login/page.tsx'),
 	route('/logout', 'routes/auth/logout.ts'),

app/routes/acls/acl-action.ts

@@ -1,40 +1,35 @@
-import { ActionFunctionArgs, data } from 'react-router';
-import { LoadContext } from '~/server';
-import ResponseError from '~/server/headscale/api-error';
+import { data } from 'react-router';
+import { isDataWithApiError } from '~/server/headscale/api/error-client';
 import { Capabilities } from '~/server/web/roles';
-import { data400, data403 } from '~/utils/res';
+import type { Route } from './+types/overview';
 
 // We only check capabilities here and assume it is writable
 // If it isn't, it'll gracefully error anyways, since this means some
 // fishy client manipulation is happening.
-export async function aclAction({
-	request,
-	context,
-}: ActionFunctionArgs<LoadContext>) {
+export async function aclAction({ request, context }: Route.ActionArgs) {
 	const session = await context.sessions.auth(request);
 	const check = await context.sessions.check(
 		request,
 		Capabilities.write_policy,
 	);
 	if (!check) {
-		throw data403('You do not have permission to write to the ACL policy');
+		throw data('You do not have permission to write to the ACL policy', {
+			status: 403,
+		});
 	}
 
 	// Try to write to the ACL policy via the API or via config file (TODO).
 	const formData = await request.formData();
 	const policyData = formData.get('policy')?.toString();
 	if (!policyData) {
-		throw data400('Missing `policy` in the form data.');
+		throw data('Missing `policy` in the form data.', {
+			status: 400,
+		});
 	}
 
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 	try {
-		const { policy, updatedAt } = await context.client.put<{
-			policy: string;
-			updatedAt: string;
-		}>('v1/policy', session.api_key, {
-			policy: policyData,
-		});
-
+		const { policy, updatedAt } = await api.setPolicy(policyData);
 		return data({
 			success: true,
 			error: undefined,
@@ -42,68 +37,99 @@ export async function aclAction({
 			updatedAt,
 		});
 	} catch (error) {
-		// This means Headscale returned a protobuf error to us
-		// It also means we 100% know this is in database mode
-		if (error instanceof ResponseError && error.responseObject?.message) {
-			const message = error.responseObject.message as string;
-			// This is stupid, refer to the link
-			// https://github.com/juanfont/headscale/blob/main/hscontrol/types/policy.go
-			if (message.includes('update is disabled')) {
-				// This means the policy is not writable
-				throw data403('Policy is not writable');
+		if (isDataWithApiError(error)) {
+			const rawData = error.data.rawData;
+			// https://github.com/juanfont/headscale/blob/c4600346f9c29b514dc9725ac103efb9d0381f23/hscontrol/types/policy.go#L11
+			if (rawData.includes('update is disabled')) {
+				throw data('Policy is not writable', { status: 403 });
 			}
 
-			// https://github.com/juanfont/headscale/blob/main/hscontrol/policy/v1/acls.go#L81
-			if (message.includes('parsing hujson')) {
-				// This means the policy was invalid, return a 400
-				// with the actual error message from Headscale
-				const cutIndex = message.indexOf('err: hujson:');
-				const trimmed =
-					cutIndex > -1
-						? `Syntax error: ${message.slice(cutIndex + 12)}`
-						: message;
+			const message =
+				error.data.data != null &&
+				'message' in error.data.data &&
+				typeof error.data.data.message === 'string'
+					? error.data.data.message
+					: undefined;
 
-				return data(
-					{
-						success: false,
-						error: trimmed,
-						policy: undefined,
-						updatedAt: undefined,
-					},
-					400,
-				);
+			if (message == null) {
+				throw error;
 			}
 
-			if (message.includes('unmarshalling policy')) {
-				// This means the policy was invalid, return a 400
-				// with the actual error message from Headscale
-				const cutIndex = message.indexOf('err:');
-				const trimmed =
-					cutIndex > -1
-						? `Syntax error: ${message.slice(cutIndex + 5)}`
-						: message;
+			// Starting in Headscale 0.27.0 the ACLs parsing was changed meaning
+			// we need to reference other error messages based on API version.
+			if (context.hsApi.clientHelpers.isAtleast('0.27.0')) {
+				if (message.includes('parsing HuJSON:')) {
+					const cutIndex = message.indexOf('parsing HuJSON:');
+					const trimmed =
+						cutIndex > -1
+							? `Syntax error: ${message.slice(cutIndex + 16).trim()}`
+							: message;
 
-				return data(
-					{
-						success: false,
-						error: trimmed,
-						policy: undefined,
-						updatedAt: undefined,
-					},
-					400,
-				);
-			}
+					return data(
+						{
+							success: false,
+							error: trimmed,
+							policy: undefined,
+							updatedAt: undefined,
+						},
+						400,
+					);
+				}
 
-			if (message.includes('empty policy')) {
-				return data(
-					{
-						success: false,
-						error: 'Policy error: Supplied policy was empty',
-						policy: undefined,
-						updatedAt: undefined,
-					},
-					400,
-				);
+				if (message.includes('parsing policy from bytes:')) {
+					const cutIndex = message.indexOf('parsing policy from bytes:');
+					const trimmed =
+						cutIndex > -1
+							? `Syntax error: ${message.slice(cutIndex + 26).trim()}`
+							: message;
+
+					return data(
+						{
+							success: false,
+							error: trimmed,
+							policy: undefined,
+							updatedAt: undefined,
+						},
+						400,
+					);
+				}
+			} else {
+				// Pre-0.27.0 error messages
+				if (message.includes('parsing hujson')) {
+					const cutIndex = message.indexOf('err: hujson:');
+					const trimmed =
+						cutIndex > -1
+							? `Syntax error: ${message.slice(cutIndex + 12)}`
+							: message;
+
+					return data(
+						{
+							success: false,
+							error: trimmed,
+							policy: undefined,
+							updatedAt: undefined,
+						},
+						400,
+					);
+				}
+
+				if (message.includes('unmarshalling policy')) {
+					const cutIndex = message.indexOf('err:');
+					const trimmed =
+						cutIndex > -1
+							? `Syntax error: ${message.slice(cutIndex + 5)}`
+							: message;
+
+					return data(
+						{
+							success: false,
+							error: trimmed,
+							policy: undefined,
+							updatedAt: undefined,
+						},
+						400,
+					);
+				}
 			}
 		}
 

app/routes/acls/acl-loader.ts

@@ -1,8 +1,7 @@
-import { LoaderFunctionArgs } from 'react-router';
-import { LoadContext } from '~/server';
-import ResponseError from '~/server/headscale/api-error';
+import { data } from 'react-router';
+import { isDataWithApiError } from '~/server/headscale/api/error-client';
 import { Capabilities } from '~/server/web/roles';
-import { data403 } from '~/utils/res';
+import type { Route } from './+types/overview';
 
 // The logic for deciding policy factors is very complicated because
 // there are so many factors that need to be accounted for:
@@ -11,15 +10,13 @@ import { data403 } from '~/utils/res';
 // 3. Is the Headscale policy in file or database mode?
 //    If database, we can read/write easily via the API.
 //    If in file mode, we can only write if context.config is available.
-// TODO: Consider adding back file editing mode instead of database
-export async function aclLoader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function aclLoader({ request, context }: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
 	const check = await context.sessions.check(request, Capabilities.read_policy);
 	if (!check) {
-		throw data403('You do not have permission to read the ACL policy.');
+		throw data('You do not have permission to read the ACL policy.', {
+			status: 403,
+		});
 	}
 
 	const flags = {
@@ -30,35 +27,22 @@ export async function aclLoader({
 	};
 
 	// Try to load the ACL policy from the API.
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 	try {
-		const { policy, updatedAt } = await context.client.get<{
-			policy: string;
-			updatedAt: string | null;
-		}>('v1/policy', session.api_key);
-
-		// Successfully loaded the policy, mark it as readable
-		// If `updatedAt` is null, it means the policy is in file mode.
+		const { policy, updatedAt } = await api.getPolicy();
 		flags.writable = updatedAt !== null;
 		flags.policy = policy;
 		return flags;
 	} catch (error) {
-		// This means Headscale returned a protobuf error to us
-		// It also means we 100% know this is in database mode
-		if (error instanceof ResponseError && error.responseObject?.message) {
-			const message = error.responseObject.message as string;
-			// This is stupid, refer to the link
-			// https://github.com/juanfont/headscale/blob/main/hscontrol/types/policy.go
-			if (message.includes('acl policy not found')) {
-				// This means the policy has never been initiated, and we can
-				// write to it to get it started or ignore it.
-				flags.policy = ''; // Start with an empty policy
+		if (isDataWithApiError(error)) {
+			// https://github.com/juanfont/headscale/blob/c4600346f9c29b514dc9725ac103efb9d0381f23/hscontrol/types/policy.go#L10
+			if (error.data.rawData.includes('acl policy not found')) {
+				flags.policy = '';
 				flags.writable = true;
+				return flags;
 			}
-
-			return flags;
 		}
 
-		// Otherwise, this is a Headscale error that we can just propagate.
 		throw error;
 	}
 }

app/routes/acls/components/cm.client.tsx

@@ -38,14 +38,14 @@ export function Editor(props: EditorProps) {
 				<ClientOnly fallback={<Fallback acl={props.value} />}>
 					{() => (
 						<CodeMirror
-							value={props.value}
-							editable={!props.isDisabled} // Allow editing unless disabled
-							readOnly={props.isDisabled} // Use readOnly if disabled
-							height="100%"
-							extensions={[shopify.jsonc()]}
+							editable={!props.isDisabled}
+							extensions={[shopify.jsonc()]} // Allow editing unless disabled
+							height="100%" // Use readOnly if disabled
+							onChange={(value) => props.onChange(value)}
+							readOnly={props.isDisabled}
 							style={{ height: '100%' }}
 							theme={light ? xcodeLight : xcodeDark}
-							onChange={(value) => props.onChange(value)}
+							value={props.value}
 						/>
 					)}
 				</ClientOnly>
@@ -92,14 +92,14 @@ export function Differ(props: DifferProps) {
 							{() => (
 								<Merge orientation="a-b" theme={light ? xcodeLight : xcodeDark}>
 									<Merge.Original
+										extensions={[shopify.jsonc()]}
 										readOnly
 										value={props.left}
-										extensions={[shopify.jsonc()]}
 									/>
 									<Merge.Modified
+										extensions={[shopify.jsonc()]}
 										readOnly
 										value={props.right}
-										extensions={[shopify.jsonc()]}
 									/>
 								</Merge>
 							)}

app/routes/acls/components/fallback.tsx

@@ -23,12 +23,12 @@ export default function Fallback({ acl }: Props) {
 				/>
 			</div>
 			<textarea
-				readOnly
 				className={cn(
 					'w-full h-editor font-mono resize-none text-sm',
 					'bg-headplane-50 dark:bg-headplane-950 opacity-60',
 					'pl-1 pt-1 leading-snug',
 				)}
+				readOnly
 				value={acl}
 			/>
 		</div>

app/routes/acls/overview.tsx

@@ -1,34 +1,31 @@
-import { Construction, Eye, FlaskConical, Pencil } from 'lucide-react';
-import { useEffect, useState } from 'react';
 import {
-	ActionFunctionArgs,
-	LoaderFunctionArgs,
-	useFetcher,
-	useLoaderData,
-	useRevalidator,
-} from 'react-router';
+	AlertCircle,
+	Construction,
+	Eye,
+	FlaskConical,
+	Pencil,
+} from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { isRouteErrorResponse, useFetcher, useRevalidator } from 'react-router';
 import Button from '~/components/Button';
+import Card from '~/components/Card';
 import Code from '~/components/Code';
 import Link from '~/components/Link';
 import Notice from '~/components/Notice';
 import Tabs from '~/components/Tabs';
-import type { LoadContext } from '~/server';
+import { isApiError } from '~/server/headscale/api/error-client';
 import toast from '~/utils/toast';
+import type { Route } from './+types/overview';
 import { aclAction } from './acl-action';
 import { aclLoader } from './acl-loader';
 import { Differ, Editor } from './components/cm.client';
 
-export async function loader(request: LoaderFunctionArgs<LoadContext>) {
-	return aclLoader(request);
-}
+export const loader = aclLoader;
+export const action = aclAction;
 
-export async function action(request: ActionFunctionArgs<LoadContext>) {
-	return aclAction(request);
-}
-
-export default function Page() {
-	// Access is a write check here, we already check read in aclLoader
-	const { access, writable, policy } = useLoaderData<typeof loader>();
+export default function Page({
+	loaderData: { access, writable, policy },
+}: Route.ComponentProps) {
 	const [codePolicy, setCodePolicy] = useState(policy);
 	const fetcher = useFetcher<typeof action>();
 	const { revalidate } = useRevalidator();
@@ -75,15 +72,15 @@ export default function Page() {
 				The ACL file is used to define the access control rules for your
 				network. You can find more information about the ACL file in the{' '}
 				<Link
-					to="https://tailscale.com/kb/1018/acls"
 					name="Tailscale ACL documentation"
+					to="https://tailscale.com/kb/1018/acls"
 				>
 					Tailscale ACL guide
 				</Link>{' '}
 				and the{' '}
 				<Link
-					to="https://headscale.net/stable/ref/acls/"
 					name="Headscale ACL documentation"
+					to="https://headscale.net/stable/ref/acls/"
 				>
 					Headscale docs
 				</Link>
@@ -91,14 +88,14 @@ export default function Page() {
 			</p>
 			{fetcher.data?.error !== undefined ? (
 				<Notice
-					variant="error"
 					title={fetcher.data.error.split(':')[0] ?? 'Error'}
+					variant="error"
 				>
 					{fetcher.data.error.split(':').slice(1).join(': ') ??
 						'An unknown error occurred while trying to update the ACL policy.'}
 				</Notice>
 			) : undefined}
-			<Tabs label="ACL Editor" className="mb-4">
+			<Tabs className="mb-4" label="ACL Editor">
 				<Tabs.Item
 					key="edit"
 					title={
@@ -110,8 +107,8 @@ export default function Page() {
 				>
 					<Editor
 						isDisabled={disabled}
-						value={codePolicy}
 						onChange={setCodePolicy}
+						value={codePolicy}
 					/>
 				</Tabs.Item>
 				<Tabs.Item
@@ -145,7 +142,6 @@ export default function Page() {
 				</Tabs.Item>
 			</Tabs>
 			<Button
-				variant="heavy"
 				className="mr-2"
 				isDisabled={
 					disabled ||
@@ -158,6 +154,7 @@ export default function Page() {
 					formData.append('policy', codePolicy);
 					fetcher.submit(formData, { method: 'PATCH' });
 				}}
+				variant="heavy"
 			>
 				Save
 			</Button>
@@ -175,3 +172,49 @@ export default function Page() {
 		</div>
 	);
 }
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+	if (
+		isRouteErrorResponse(error) &&
+		isApiError(error.data) &&
+		error.data.rawData.includes('reading policy from path') &&
+		error.data.rawData.includes('no such file or directory')
+	) {
+		return (
+			<div className="flex flex-col gap-4">
+				<Card className="max-w-2xl" variant="flat">
+					<div className="flex items-center justify-between gap-4">
+						<Card.Title>ACL Policy Unavailable</Card.Title>
+						<AlertCircle className="w-6 h-6 mb-2 text-red-500" />
+					</div>
+					<Card.Text>
+						The ACL policy is currently unavailable because the policy file does
+						not exist on the server. This usually indicates that Headscale is
+						running in <Code>file</Code> mode for ACLs, and the specified policy
+						file is missing.
+					</Card.Text>
+				</Card>
+				<Card className="max-w-2xl" variant="flat">
+					<Card.Text>
+						In order to resolve this issue, there are two possible actions you
+						can take:
+					</Card.Text>
+					<ul className="list-disc list-outside mt-2 ml-4 space-y-1 text-sm">
+						<li>
+							Create the ACL policy file at the specified path in your Headscale
+							configuration.
+						</li>
+						<li>
+							Alternatively, you can switch Headscale to use{' '}
+							<Code>database</Code> mode for ACLs by updating your Headscale
+							configuration. This will allow Headplane to manage the ACL policy
+							directly through the web interface.
+						</li>
+					</ul>
+				</Card>
+			</div>
+		);
+	}
+
+	throw error;
+}

app/routes/auth/login/action.ts

@@ -1,13 +1,9 @@
-import { ActionFunctionArgs, data, redirect } from 'react-router';
-import { LoadContext } from '~/server';
-import ResponseError from '~/server/headscale/api-error';
-import { Key } from '~/types';
+import { data, redirect } from 'react-router';
+import { isDataWithApiError } from '~/server/headscale/api/error-client';
 import log from '~/utils/log';
+import type { Route } from './+types/page';
 
-export async function loginAction({
-	request,
-	context,
-}: ActionFunctionArgs<LoadContext>) {
+export async function loginAction({ request, context }: Route.LoaderArgs) {
 	const formData = await request.formData();
 	const apiKey = formData.has('api_key')
 		? String(formData.get('api_key'))
@@ -31,11 +27,9 @@ export async function loginAction({
 		throw data('Received an empty `api_key`', { status: 400 });
 	}
 
+	const api = context.hsApi.getRuntimeClient(apiKey);
 	try {
-		const { apiKeys } = await context.client.get<{ apiKeys: Key[] }>(
-			'v1/apikey',
-			apiKey,
-		);
+		const apiKeys = await api.getApiKeys();
 
 		// We don't need to check for 0 API keys because this request cannot
 		// be authenticated correctly without an API key
@@ -80,12 +74,15 @@ export async function loginAction({
 			},
 		});
 	} catch (error) {
-		if (error instanceof ResponseError) {
+		// Check if this is a React Router DataWithResponseInit wrapping a Headscale API error
+		if (isDataWithApiError(error)) {
+			const apiError = error.data;
 			// TODO: What in gods name is wrong with the headscale API?
 			if (
-				error.status === 401 ||
-				error.status === 403 ||
-				(error.status === 500 && error.response.trim() === 'Unauthorized')
+				apiError.statusCode === 401 ||
+				apiError.statusCode === 403 ||
+				(apiError.statusCode === 500 &&
+					apiError.rawData.trim() === 'Unauthorized')
 			) {
 				return {
 					success: false,

app/routes/auth/login/config-error.tsx

@@ -0,0 +1,123 @@
+import { AlertCircle } from 'lucide-react';
+import Card from '~/components/Card';
+import Code from '~/components/Code';
+import Link from '~/components/Link';
+import { OidcConnectorError } from '~/server/web/oidc-connector';
+
+export function OidcConfigErrorNotice({
+	errors,
+}: {
+	errors: OidcConnectorError[];
+}) {
+	return (
+		<Card className="max-w-md m-4 sm:m-0 mb-4 sm:mb-4 border border-red-500">
+			<div className="flex items-center justify-between gap-4">
+				<Card.Title className="text-red-500">Authentication Error</Card.Title>
+				<AlertCircle className="w-6 h-6 mb-2 text-red-500" />
+			</div>
+			<Card.Text className="text-sm">
+				The OpenID Connect (OIDC) Single Sign-On (SSO) configuration has issues:{' '}
+				<ul className="list-disc list-inside mt-2 mb-1">
+					{mapOidcErrorsToMessages(errors).map((code) => (
+						<li key={code.key}>{code.node}</li>
+					))}
+				</ul>{' '}
+				<Link
+					name="Headplane OIDC Issues"
+					to="https://headplane.net/configuration/sso#troubleshooting"
+				>
+					Learn more
+				</Link>
+			</Card.Text>
+		</Card>
+	);
+}
+
+function mapOidcErrorsToMessages(errors: OidcConnectorError[]) {
+	const messages: {
+		key: string;
+		node: React.ReactNode;
+	}[] = [];
+
+	for (const error of errors) {
+		switch (error) {
+			case 'INVALID_API_KEY':
+				messages.push({
+					key: error,
+					node: (
+						<Card.Text className="inline">
+							The provided API key for OIDC authentication is invalid. Ensure
+							that <Code>oidc.headscale_api_key</Code> is a valid API key.
+						</Card.Text>
+					),
+				});
+				break;
+
+			case 'MISSING_AUTHORIZATION_ENDPOINT':
+				messages.push({
+					key: error,
+					node: (
+						<Card.Text className="inline">
+							The OIDC provided does not have a configured{' '}
+							<Code>authorization_endpoint</Code>. Ensure discovery URL or
+							manual configuration is correct.
+						</Card.Text>
+					),
+				});
+				break;
+
+			case 'MISSING_TOKEN_ENDPOINT':
+				messages.push({
+					key: error,
+					node: (
+						<Card.Text className="inline">
+							The OIDC provided does not have a configured{' '}
+							<Code>token_endpoint</Code>. Ensure discovery URL or manual
+							configuration is correct.
+						</Card.Text>
+					),
+				});
+				break;
+
+			case 'MISSING_USERINFO_ENDPOINT':
+				messages.push({
+					key: error,
+					node: (
+						<Card.Text className="inline">
+							The OIDC provided does not have a configured{' '}
+							<Code>user_endpoint</Code>. Ensure discovery URL or manual
+							configuration is correct.
+						</Card.Text>
+					),
+				});
+				break;
+
+			case 'MISSING_REQUIRED_CLAIMS':
+				messages.push({
+					key: error,
+					node: (
+						<Card.Text className="inline">
+							The OIDC provider does not support the <Code>sub</Code> claim,
+							which is required for authentication. Your OIDC provider may be
+							misconfigured.
+						</Card.Text>
+					),
+				});
+				break;
+
+			case 'UNKNOWN_ERROR':
+				messages.push({
+					key: error,
+					node: (
+						<Card.Text className="inline">
+							An unknown error occurred during OIDC configuration. Please check
+							the Headplane logs for more information.
+						</Card.Text>
+					),
+				});
+				break;
+		}
+	}
+
+	return messages;
+}

app/routes/auth/login/oidc-error.tsx

@@ -0,0 +1,63 @@
+import { AlertCircle } from 'lucide-react';
+import Card from '~/components/Card';
+import Code from '~/components/Code';
+
+export function OidcErrorNotice({ code }: { code: string }) {
+	return (
+		<Card className="max-w-md m-4 sm:m-0 mb-4 sm:mb-4 border border-red-500">
+			<div className="flex items-center justify-between gap-4">
+				<Card.Title className="text-red-500">Configuration Issue(s)</Card.Title>
+				<AlertCircle className="w-6 h-6 mb-2 text-red-500" />
+			</div>
+			{getErrorMessage(code)}
+		</Card>
+	);
+}
+
+function getErrorMessage(code: string) {
+	switch (code) {
+		case 'error_no_query':
+			return (
+				<Card.Text>
+					The SSO provider did not correctly redirect back to Headplane with the
+					required parameters. Please ensure your SSO provider is configured
+					correctly.
+				</Card.Text>
+			);
+
+		case 'error_no_session':
+		case 'error_invalid_session':
+			return (
+				<Card.Text>
+					Unable to complete SSO login due to missing or invalid session data.
+					Ensure that your Headplane cookie configuration is correct and that
+					your browser is accepting cookies.
+				</Card.Text>
+			);
+
+		case 'error_no_sub':
+			return (
+				<Card.Text>
+					The SSO provider did not return a valid user identifier. Please ensure
+					your SSO provider is correctly configured to provide the{' '}
+					<Code>sub</Code> claim.
+				</Card.Text>
+			);
+
+		case 'error_auth_failed':
+			return (
+				<Card.Text>
+					Authentication with the SSO provider failed. Please try again later.
+					Headplane logs may provide more information.
+				</Card.Text>
+			);
+
+		default:
+			return (
+				<Card.Text>
+					An unknown error occurred during OIDC authentication. Please try again
+					later.
+				</Card.Text>
+			);
+	}
+}

app/routes/auth/login/page.tsx

@@ -1,78 +1,78 @@
-import { useEffect } from 'react';
+import { AlertCircle } from 'lucide-react';
+import { useEffect, useState } from 'react';
 import {
-	ActionFunctionArgs,
-	data,
 	Form,
-	LoaderFunctionArgs,
 	Link as RemixLink,
 	redirect,
-	useActionData,
-	useLoaderData,
 	useSearchParams,
 } from 'react-router';
 import Button from '~/components/Button';
 import Card from '~/components/Card';
 import Code from '~/components/Code';
 import Input from '~/components/Input';
-import type { LoadContext } from '~/server';
+import Link from '~/components/Link';
 import { useLiveData } from '~/utils/live-data';
+import type { Route } from './+types/page';
 import { loginAction } from './action';
+import { OidcConfigErrorNotice } from './config-error';
 import Logout from './logout';
+import { OidcErrorNotice } from './oidc-error';
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	try {
 		await context.sessions.auth(request);
 		return redirect('/machines');
 	} catch {}
 
 	const qp = new URL(request.url).searchParams;
-	const state = qp.get('s') ?? undefined;
-
-	// OIDC config cannot be undefined if an OIDC client is set
-	// Also check if we are in a logout state and skip redirect if we are
-	const ssoOnly = context.config.oidc?.disable_api_key_login;
-	if (state !== 'logout' && ssoOnly) {
-		// This shouldn't be possible, but still a safe sanity check
-		if (!context.oidc) {
-			throw data(
-				'`oidc.disable_api_key_login` was set without a valid OIDC configuration',
-				{
-					status: 400,
-				},
-			);
-		}
+	const urlState = qp.get('s') ?? undefined;
 
+	// MARK: This works because the OIDC connector will always return false
+	// for `isExclusive` if the OIDC config isn't usable.
+	if (context.oidcConnector?.isExclusive && urlState !== 'logout') {
 		return redirect('/oidc/start');
 	}
 
+	const isOidcConnectorEnabled = context.oidcConnector?.isValid;
+	const oidcErrorCodes = !isOidcConnectorEnabled
+		? (context.oidcConnector?.errors ?? [])
+		: [];
+
 	return {
-		oidc: context.oidc,
-		state,
+		isCookieSecureEnabled: context.config.server.cookie_secure,
+		isOidcConnectorEnabled,
+		oidcErrorCodes,
+		urlState,
 	};
 }
 
-export async function action(request: ActionFunctionArgs<LoadContext>) {
-	return loginAction(request);
-}
+export const action = loginAction;
 
-export default function Page() {
-	const { state, oidc } = useLoaderData<typeof loader>();
-	const formData = useActionData<typeof action>();
+export default function Page({ loaderData, actionData }: Route.ComponentProps) {
+	const {
+		isCookieSecureEnabled,
+		isOidcConnectorEnabled,
+		oidcErrorCodes,
+		urlState,
+	} = loaderData;
+
+	const [showCookieWarning, setShowCookieWarning] = useState(false);
 	const [params] = useSearchParams();
 	const { pause } = useLiveData();
 
 	useEffect(() => {
 		// This page does NOT need stale while revalidate logic
 		pause();
+
+		if (isCookieSecureEnabled && window.location.protocol !== 'https:') {
+			setShowCookieWarning(true);
+		}
 	});
 
 	useEffect(() => {
 		// State is a one time thing, we need to remove it after it has
 		// been consumed to prevent logic loops.
-		if (state !== null) {
+		if (urlState !== null) {
 			const searchParams = new URLSearchParams(params);
 			searchParams.delete('s');
 
@@ -85,48 +85,81 @@ export default function Page() {
 
 			window.history.replaceState(null, '', newUrl);
 		}
-	}, [state, params]);
+	}, [urlState, params]);
 
-	if (state === 'logout') {
+	if (urlState === 'logout') {
 		return <Logout />;
 	}
 
 	return (
 		<div className="flex w-screen h-screen items-center justify-center">
-			<Card className="max-w-md m-4 sm:m-0">
-				<Card.Title>Welcome to Headplane</Card.Title>
-				<Form method="POST">
-					<Card.Text>
-						Enter an API key to authenticate with Headplane. You can generate
-						one by running <Code>headscale apikeys create</Code> in your
-						terminal.
-					</Card.Text>
-					<Input
-						className="mt-8 mb-2"
-						isRequired
-						label="API Key"
-						labelHidden
-						name="api_key"
-						placeholder="API Key"
-						type="password"
-					/>
-					{formData?.success === false ? (
-						<Card.Text className="text-sm mb-2 text-red-600 dark:text-red-300">
-							{formData.message}
-						</Card.Text>
-					) : undefined}
-					<Button className="w-full" type="submit" variant="heavy">
-						Sign In
-					</Button>
-				</Form>
-				{oidc ? (
-					<RemixLink to="/oidc/start">
-						<Button className="w-full mt-2" variant="light">
-							Single Sign-On
-						</Button>
-					</RemixLink>
+			<div>
+				{urlState?.startsWith('error_') ? (
+					<OidcErrorNotice code={urlState} />
+				) : oidcErrorCodes.length > 0 ? (
+					<OidcConfigErrorNotice errors={oidcErrorCodes} />
+				) : showCookieWarning ? (
+					<Card className="max-w-md m-4 sm:m-0 mb-4 sm:mb-4 border border-red-500">
+						<div className="flex items-center justify-between gap-4">
+							<Card.Title className="text-red-500">
+								Configuration Issue
+							</Card.Title>
+							<AlertCircle className="w-6 h-6 mb-2 text-red-500" />
+						</div>
+						{showCookieWarning ? (
+							<Card.Text className="text-sm">
+								Headplane is configured to use secure cookies, but this site is
+								being served over an insecure connection and login will not work
+								correctly.{' '}
+								<Link
+									name="Headplane Common Issues"
+									to="https://headplane.net/configuration/common-issues#issue-logging-in-does-not-do-anything"
+								>
+									Learn more.
+								</Link>
+							</Card.Text>
+						) : undefined}
+					</Card>
 				) : undefined}
-			</Card>
+				<Card className="max-w-md m-4 sm:m-0">
+					<Card.Title>Welcome to Headplane</Card.Title>
+					<Form method="POST">
+						<Card.Text>
+							Enter an API key to authenticate with Headplane. You can generate
+							one by running <Code>headscale apikeys create</Code> in your
+							terminal.
+						</Card.Text>
+						<Input
+							className="mt-8 mb-2"
+							isRequired
+							label="API Key"
+							labelHidden
+							name="api_key"
+							placeholder="API Key"
+							type="password"
+						/>
+						{actionData?.success === false ? (
+							<Card.Text className="text-sm mb-2 text-red-600 dark:text-red-300">
+								{actionData.message}
+							</Card.Text>
+						) : undefined}
+						<Button className="w-full" type="submit" variant="heavy">
+							Sign In
+						</Button>
+					</Form>
+					{isOidcConnectorEnabled ? (
+						<RemixLink to="/oidc/start">
+							<Button
+								className="w-full mt-2"
+								isDisabled={oidcErrorCodes.length > 0}
+								variant="light"
+							>
+								Single Sign-On
+							</Button>
+						</RemixLink>
+					) : undefined}
+				</Card>
+			</div>
 		</div>
 	);
 }

app/routes/auth/oidc-callback.ts

@@ -1,75 +1,90 @@
 import { createHash } from 'node:crypto';
 import { count, eq } from 'drizzle-orm';
-import { createCookie, type LoaderFunctionArgs, redirect } from 'react-router';
+import * as oidc from 'openid-client';
+import { data, redirect } from 'react-router';
 import { ulid } from 'ulidx';
-import type { LoadContext } from '~/server';
-import { HeadplaneConfig } from '~/server/config/schema';
 import { users } from '~/server/db/schema';
 import { Roles } from '~/server/web/roles';
-import { FlowUser, finishAuthFlow, formatError } from '~/utils/oidc';
-import { send } from '~/utils/res';
+import log from '~/utils/log';
+import { createOidcStateCookie } from '~/utils/oidc-state';
+import type { Route } from './+types/oidc-callback';
 
-interface OidcFlowSession {
-	state: string;
-	nonce: string;
-	code_verifier: string;
-	redirect_uri: string;
-}
-
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
-	if (!context.oidc) {
-		throw new Error('OIDC is not enabled');
+export async function loader({ request, context }: Route.LoaderArgs) {
+	if (!context.oidcConnector?.isValid) {
+		throw data('OIDC is not enabled or misconfigured', { status: 501 });
 	}
 
-	// Check if we have 0 query parameters
 	const url = new URL(request.url);
 	if (url.searchParams.toString().length === 0) {
-		return redirect('/login');
+		return redirect('/login?s=error_no_query');
 	}
 
-	const cookie = createCookie('__oidc_auth_flow', {
-		httpOnly: true,
-		maxAge: 300, // 5 minutes
-	});
+	const cookie = createOidcStateCookie(context.config);
+	const oidcCookieState = await cookie.parse(request.headers.get('Cookie'));
 
-	const data: OidcFlowSession | null = await cookie.parse(
-		request.headers.get('Cookie'),
-	);
-
-	if (data === null) {
-		console.warn('OIDC flow session not found');
-		return redirect('/login');
+	if (oidcCookieState == null) {
+		log.warn('auth', 'Called OIDC callback without session cookie');
+		return redirect('/login?s=error_no_session');
 	}
 
-	const { code_verifier, state, nonce, redirect_uri } = data;
-	if (!code_verifier || !state || !nonce || !redirect_uri) {
-		return send({ error: 'Missing OIDC state' }, { status: 400 });
+	const { state, nonce, redirect_uri, verifier } = oidcCookieState;
+	if (!state || !nonce || !redirect_uri || !verifier) {
+		log.warn('auth', 'OIDC session cookie is missing required fields');
+		return redirect('/login?s=error_invalid_session');
 	}
 
-	// Reconstruct the redirect URI using the query parameters
-	// and the one we saved in the session
-	const flowRedirectUri = new URL(redirect_uri);
-	flowRedirectUri.search = url.search;
-
-	const flowOptions = {
-		redirect_uri: flowRedirectUri.toString(),
-		code_verifier,
-		state,
-		nonce: nonce === '<none>' ? undefined : nonce,
-	};
-
 	try {
-		let user = await finishAuthFlow(context.oidc, flowOptions);
-		user = {
-			...user,
-			picture: setOidcPictureForSource(
-				user,
-				context.config.oidc?.profile_picture_source ?? 'oidc',
-			),
-		};
+		const callbackUrl = new URL(redirect_uri);
+		const currentUrl = new URL(request.url);
+		callbackUrl.search = currentUrl.search;
+
+		const tokens = await oidc.authorizationCodeGrant(
+			context.oidcConnector.client,
+			callbackUrl,
+			{
+				expectedState: state,
+				expectedNonce: nonce,
+				...(context.oidcConnector.usePKCE
+					? { pkceCodeVerifier: verifier }
+					: {}),
+			},
+		);
+
+		const claims = tokens.claims();
+		if (claims?.sub == null) {
+			log.warn('auth', 'No subject found in OIDC claims');
+			return redirect('/login?s=error_no_sub');
+		}
+
+		const userInfo = await oidc.fetchUserInfo(
+			context.oidcConnector.client,
+			tokens.access_token,
+			claims.sub,
+		);
+
+		// We have defaults that closely follow what Headscale uses, maybe we
+		// can make it configurable in the future, but for now we only need the
+		// `sub` claim.
+		const username =
+			userInfo.preferred_username ?? userInfo.email?.split('@')[0] ?? 'user';
+		const name =
+			userInfo.name ??
+			(userInfo.given_name && userInfo.family_name
+				? `${userInfo.given_name} ${userInfo.family_name}`
+				: (userInfo.preferred_username ?? 'SSO User'));
+
+		const picture =
+			context.config.oidc?.profile_picture_source === 'gravatar'
+				? (() => {
+						if (!userInfo.email) {
+							return undefined;
+						}
+
+						const emailHash = userInfo.email.trim().toLowerCase();
+						const hash = createHash('sha256').update(emailHash).digest('hex');
+						return `https://www.gravatar.com/avatar/${hash}?s=200&d=identicon&r=x`;
+					})()
+				: userInfo.picture;
 
 		const [{ count: userCount }] = await context.db
 			.select({ count: count() })
@@ -80,52 +95,77 @@ export async function loader({
 			.insert(users)
 			.values({
 				id: ulid(),
-				sub: user.subject,
+				sub: claims.sub,
 				caps: userCount === 0 ? Roles.owner : Roles.member,
 			})
 			.onConflictDoNothing();
 
-		return redirect('/machines', {
+		return redirect('/', {
 			headers: {
 				'Set-Cookie': await context.sessions.createSession({
-					// TODO: This is breaking, to stop the "over-generation" of API
-					// keys because they are currently non-deletable in the headscale
-					// database. Look at this in the future once we have a solution
-					// or we have permissioned API keys.
-					api_key: context.config.oidc?.headscale_api_key!,
-					user,
+					api_key: context.oidcConnector.apiKey,
+					user: {
+						subject: claims.sub,
+						username,
+						name,
+						email: userInfo.email,
+						picture,
+					},
 				}),
 			},
 		});
 	} catch (error) {
-		return new Response(JSON.stringify(formatError(error)), {
-			status: 500,
-			headers: {
-				'Content-Type': 'application/json',
-			},
-		});
-	}
-}
+		if (error instanceof oidc.ResponseBodyError) {
+			log.error(
+				'auth',
+				'Got an OIDC response error body: %s',
+				JSON.stringify(error.cause),
+			);
 
-type PictureSource = NonNullable<
-	HeadplaneConfig['oidc']
->['profile_picture_source'];
+			// Check for PKCE-related errors
+			if (
+				error.error.toLowerCase().includes('code_verifier') ||
+				error.error.toLowerCase().includes('code verifier') ||
+				error.error.toLowerCase().includes('pkce')
+			) {
+				log.error(
+					'auth',
+					'PKCE error detected. Your OIDC provider may require PKCE to be enabled. Current setting: use_pkce=%s',
+					context.oidcConnector?.usePKCE,
+				);
 
-function setOidcPictureForSource(user: FlowUser, source: PictureSource) {
-	// Already set by default in the callback, so we can just return it
-	if (source === 'oidc') {
-		return user.picture;
-	}
-
-	if (source === 'gravatar') {
-		if (!user.email) {
-			return undefined;
+				if (!context.oidcConnector?.usePKCE) {
+					log.error(
+						'auth',
+						'Consider setting oidc.use_pkce=true in your configuration if your provider requires PKCE',
+					);
+				}
+			}
+		} else if (error instanceof oidc.AuthorizationResponseError) {
+			log.error(
+				'auth',
+				'Got an OIDC authorization response error: %s',
+				error.error,
+			);
+		} else if (error instanceof oidc.WWWAuthenticateChallengeError) {
+			log.error('auth', 'Got an OIDC WWW-Authenticate challenge error');
+		} else if (error instanceof oidc.ClientError) {
+			log.error(
+				'auth',
+				'Got an OIDC authorization client error: %s',
+				error.cause instanceof Error
+					? error.cause.message
+					: String(error.cause),
+			);
+		} else {
+			log.error(
+				'auth',
+				'Got an OIDC error: %s',
+				error instanceof Error && error.cause
+					? JSON.stringify(error.cause)
+					: String(error),
+			);
 		}
-
-		const emailHash = user.email.trim().toLowerCase();
-		const hash = createHash('sha256').update(emailHash).digest('hex');
-		return `https://www.gravatar.com/avatar/${hash}?s=200&d=identicon&r=x`;
+		return redirect('/login?s=error_auth_failed');
 	}
-
-	return undefined;
 }

app/routes/auth/oidc-start.ts

@@ -1,43 +1,84 @@
-import { createCookie, type LoaderFunctionArgs, redirect } from 'react-router';
-import type { LoadContext } from '~/server';
-import { beginAuthFlow, getRedirectUri } from '~/utils/oidc';
+import * as oidc from 'openid-client';
+import { data, redirect } from 'react-router';
+import { HeadplaneConfig } from '~/server/config/config-schema';
+import { createOidcStateCookie } from '~/utils/oidc-state';
+import type { Route } from './+types/oidc-start';
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	try {
 		await context.sessions.auth(request);
-		return redirect('/machines');
+		return redirect('/');
 	} catch {}
 
-	if (!context.oidc || !context.config.oidc) {
-		throw new Error('OIDC is not enabled');
+	if (!context.oidcConnector?.isValid) {
+		throw data('OIDC is not enabled or misconfigured', { status: 501 });
 	}
 
-	const cookie = createCookie('__oidc_auth_flow', {
-		httpOnly: true,
-		maxAge: 300, // 5 minutes
+	const cookie = createOidcStateCookie(context.config);
+	const redirect_uri = getRedirectUri(context.config, request);
+
+	const nonce = oidc.randomNonce();
+	const verifier = oidc.randomPKCECodeVerifier();
+	const state = oidc.randomState();
+
+	const url = oidc.buildAuthorizationUrl(context.oidcConnector.client, {
+		...(context.oidcConnector.extraParams ?? {}),
+		scope: context.oidcConnector.scope,
+		redirect_uri,
+		state,
+		nonce,
+		...(context.oidcConnector.usePKCE
+			? {
+					code_challenge_method: 'S256',
+					code_challenge: await oidc.calculatePKCECodeChallenge(verifier),
+				}
+			: {}),
 	});
 
-	const redirectUri =
-		context.config.oidc?.redirect_uri ?? getRedirectUri(request);
-	const data = await beginAuthFlow(
-		context.oidc,
-		redirectUri,
-		context.config.oidc.scope,
-		context.config.oidc.extra_params,
-	);
-
-	return redirect(data.url, {
+	return redirect(url.href, {
 		status: 302,
 		headers: {
 			'Set-Cookie': await cookie.serialize({
-				state: data.state,
-				nonce: data.nonce,
-				code_verifier: data.codeVerifier,
-				redirect_uri: redirectUri,
+				state,
+				nonce,
+				verifier,
+				redirect_uri,
 			}),
 		},
 	});
 }
+
+function getRedirectUri(config: HeadplaneConfig, req: Request): string {
+	if (config.server.base_url != null) {
+		const url = new URL(`${__PREFIX__}/oidc/callback`, config.server.base_url);
+		return url.href;
+	}
+
+	if (config.oidc?.redirect_uri != null) {
+		const url = new URL(
+			`${__PREFIX__}/oidc/callback`,
+			config.oidc.redirect_uri,
+		);
+		return url.href;
+	}
+
+	const url = new URL(`${__PREFIX__}/oidc/callback`, req.url);
+	let host = req.headers.get('Host');
+	if (!host) {
+		host = req.headers.get('X-Forwarded-Host');
+	}
+
+	if (!host) {
+		throw data(
+			'Cannot determine redirect URI: no Host or X-Forwarded-Host header',
+			{
+				status: 500,
+			},
+		);
+	}
+
+	const proto = req.headers.get('X-Forwarded-Proto');
+	url.protocol = proto ?? 'http:';
+	url.host = host;
+	return url.href;
+}

app/routes/dns/components/manage-domains.tsx

@@ -1,18 +1,18 @@
-import { DndContext, DragOverlay, closestCorners } from '@dnd-kit/core';
+import { closestCorners, DndContext, DragOverlay } from '@dnd-kit/core';
 import {
 	restrictToParentElement,
 	restrictToVerticalAxis,
 } from '@dnd-kit/modifiers';
 import {
-	SortableContext,
 	arrayMove,
+	SortableContext,
 	useSortable,
 	verticalListSortingStrategy,
 } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { GripVertical, Lock } from 'lucide-react';
 import { useEffect, useState } from 'react';
-import { type FetcherWithComponents, Form, useFetcher } from 'react-router';
+import { Form } from 'react-router';
 import Button from '~/components/Button';
 import Input from '~/components/Input';
 import TableList from '~/components/TableList';
@@ -37,18 +37,15 @@ export default function ManageDomains({
 	}, [searchDomains]);
 
 	return (
-		<div className="flex flex-col w-2/3">
+		<div className="flex flex-col w-full sm:w-2/3">
 			<h1 className="text-2xl font-medium mb-4">Search Domains</h1>
 			<p className="mb-4">
 				Set custom DNS search domains for your Tailnet. When using Magic DNS,
 				your tailnet domain is used as the first search domain.
 			</p>
 			<DndContext
-				modifiers={[restrictToVerticalAxis, restrictToParentElement]}
 				collisionDetection={closestCorners}
-				onDragStart={(event) => {
-					setActiveId(event.active.id);
-				}}
+				modifiers={[restrictToVerticalAxis, restrictToParentElement]}
 				onDragEnd={(event) => {
 					setActiveId(null);
 					const { active, over } = event;
@@ -70,6 +67,9 @@ export default function ManageDomains({
 						setLocalDomains(arrayMove(localDomains, oldIndex, newIndex));
 					}
 				}}
+				onDragStart={(event) => {
+					setActiveId(event.active.id);
+				}}
 			>
 				<TableList>
 					{magic ? (
@@ -91,19 +91,19 @@ export default function ManageDomains({
 					>
 						{localDomains.map((sd, index) => (
 							<Domain
-								key={sd}
 								domain={sd}
 								id={index + 1}
 								isDisabled={isDisabled}
+								key={sd}
 							/>
 						))}
 						<DragOverlay adjustScale>
 							{activeId ? (
 								<Domain
-									isDragging
 									domain={localDomains[(activeId as number) - 1]}
 									id={(activeId as number) - 1}
 									isDisabled={isDisabled}
+									isDragging
 								/>
 							) : undefined}
 						</DragOverlay>
@@ -111,28 +111,28 @@ export default function ManageDomains({
 					{isDisabled ? undefined : (
 						<TableList.Item key="add-sd">
 							<Form
-								method="POST"
 								className="flex items-center justify-between w-full"
+								method="POST"
 							>
-								<input type="hidden" name="action_id" value="add_domain" />
+								<input name="action_id" type="hidden" value="add_domain" />
 								<Input
-									type="text"
 									className={cn(
 										'border-none font-mono p-0 text-sm',
 										'rounded-none focus:ring-0 w-full ml-1',
 									)}
-									placeholder="Search Domain"
-									label="Search Domain"
-									name="domain"
-									labelHidden
 									isRequired
+									label="Search Domain"
+									labelHidden
+									name="domain"
+									placeholder="Search Domain"
+									type="text"
 								/>
 								<Button
-									type="submit"
 									className={cn(
 										'px-2 py-1 rounded-md',
 										'text-blue-500 dark:text-blue-400',
 									)}
+									type="submit"
 								>
 									Add
 								</Button>
@@ -164,11 +164,11 @@ function Domain({ domain, id, isDragging, isDisabled }: DomainProps) {
 
 	return (
 		<TableList.Item
-			ref={setNodeRef}
 			className={cn(
 				isSortableDragging ? 'opacity-50' : '',
 				isDragging ? 'ring-3 bg-white dark:bg-headplane-900' : '',
 			)}
+			ref={setNodeRef}
 			style={{
 				transform: CSS.Transform.toString(transform),
 				transition,
@@ -186,15 +186,15 @@ function Domain({ domain, id, isDragging, isDisabled }: DomainProps) {
 			</p>
 			{isDragging ? undefined : (
 				<Form method="POST">
-					<input type="hidden" name="action_id" value="remove_domain" />
-					<input type="hidden" name="domain" value={domain} />
+					<input name="action_id" type="hidden" value="remove_domain" />
+					<input name="domain" type="hidden" value={domain} />
 					<Button
-						type="submit"
-						isDisabled={isDisabled}
 						className={cn(
 							'px-2 py-1 rounded-md',
 							'text-red-500 dark:text-red-400',
 						)}
+						isDisabled={isDisabled}
+						type="submit"
 					>
 						Remove
 					</Button>

app/routes/dns/components/manage-ns.tsx

@@ -20,14 +20,14 @@ export default function ManageNS({
 	overrideLocalDns,
 }: Props) {
 	return (
-		<div className="flex flex-col w-2/3">
+		<div className="flex flex-col w-full sm:w-2/3">
 			<h1 className="text-2xl font-medium mb-4">Nameservers</h1>
 			<p>
 				Set the nameservers used by devices on the Tailnet to resolve DNS
 				queries.{' '}
 				<Link
-					to="https://tailscale.com/kb/1054/dns"
 					name="Tailscale DNS Documentation"
+					to="https://tailscale.com/kb/1054/dns"
 				>
 					Learn more
 				</Link>
@@ -35,12 +35,12 @@ export default function ManageNS({
 			<div className="mt-4">
 				{Object.keys(nameservers).map((key) => (
 					<NameserverList
-						key={key}
-						isGlobal={key === 'global'}
 						isDisabled={isDisabled}
+						isGlobal={key === 'global'}
+						key={key}
+						name={key}
 						nameservers={nameservers}
 						overrideLocalDns={overrideLocalDns}
-						name={key}
 					/>
 				))}
 
@@ -66,16 +66,17 @@ function NameserverList({
 	name,
 }: ListProps) {
 	const list = isGlobal ? nameservers.global : nameservers[name];
+	const submit = useSubmit();
+
 	if (list.length === 0) {
 		return null;
 	}
 
-	const submit = useSubmit();
 	return (
 		<div className="mb-8">
 			<div className="flex items-center justify-between mb-2">
 				{isGlobal ? (
-					<div className="flex items-center justify-between w-full">
+					<div className="flex flex-col sm:flex-row sm:items-center sm:justify-between w-full gap-2">
 						<h2 className="text-md font-medium opacity-80">
 							Global Nameservers
 						</h2>
@@ -87,8 +88,8 @@ function NameserverList({
 									names outside the tailnet. When disabled (default), devices
 									will prefer their local DNS configuration.
 									<Link
-										to="https://tailscale.com/kb/1054/dns#global-nameservers"
 										name="Tailscale Global Nameservers Documentation"
+										to="https://tailscale.com/kb/1054/dns#global-nameservers"
 									>
 										Learn More
 									</Link>
@@ -96,11 +97,10 @@ function NameserverList({
 							</Tooltip>
 							<p>Override DNS servers</p>
 							<Switch
-								label="Override local DNS settings"
-								className="h-[15px] w-[23px] p-[2px]"
-								switchClassName="h-[9px] w-[9px]"
-								name="override_dns"
+								className="h-[15px] w-[23px] p-0.5"
 								defaultSelected={overrideLocalDns}
+								label="Override local DNS settings"
+								name="override_dns"
 								onChange={(v) => {
 									submit(
 										{
@@ -112,6 +112,7 @@ function NameserverList({
 										},
 									);
 								}}
+								switchClassName="h-[9px] w-[9px]"
 							/>
 						</div>
 					</div>
@@ -125,20 +126,20 @@ function NameserverList({
 							<TableList.Item key={ns}>
 								<p className="font-mono text-sm">{ns}</p>
 								<Form method="POST">
-									<input type="hidden" name="action_id" value="remove_ns" />
-									<input type="hidden" name="ns" value={ns} />
+									<input name="action_id" type="hidden" value="remove_ns" />
+									<input name="ns" type="hidden" value={ns} />
 									<input
-										type="hidden"
 										name="split_name"
+										type="hidden"
 										value={isGlobal ? 'global' : name}
 									/>
 									<Button
-										isDisabled={isDisabled}
-										type="submit"
 										className={cn(
 											'px-2 py-1 rounded-md',
 											'text-red-500 dark:text-red-400',
 										)}
+										isDisabled={isDisabled}
+										type="submit"
 									>
 										Remove
 									</Button>

app/routes/dns/components/manage-records.tsx

@@ -13,14 +13,14 @@ interface Props {
 
 export default function ManageRecords({ records, isDisabled }: Props) {
 	return (
-		<div className="flex flex-col w-2/3">
+		<div className="flex flex-col w-full sm:w-2/3">
 			<h1 className="text-2xl font-medium mb-4">DNS Records</h1>
 			<p>
 				Headscale supports adding custom DNS records to your Tailnet. As of now,
 				only <Code>A</Code> and <Code>AAAA</Code> records are supported.{' '}
 				<Link
-					to="https://headscale.net/stable/ref/dns"
 					name="Headscale DNS Records documentation"
+					to="https://headscale.net/stable/ref/dns"
 				>
 					Learn More
 				</Link>
@@ -32,7 +32,7 @@ export default function ManageRecords({ records, isDisabled }: Props) {
 							<p className="opacity-50 mx-auto">No DNS records found</p>
 						</TableList.Item>
 					) : (
-						records.map((record, index) => (
+						records.map((record) => (
 							<TableList.Item key={`${record.name}-${record.value}`}>
 								<div className="flex gap-2 items-center w-full">
 									<p
@@ -43,22 +43,24 @@ export default function ManageRecords({ records, isDisabled }: Props) {
 									>
 										{record.type}
 									</p>
-									<div className="grid grid-cols-2 gap-2 w-full">
-										<p className="font-mono text-sm">{record.name}</p>
-										<p className="font-mono text-sm">{record.value}</p>
+									<div className="flex flex-col sm:flex-row sm:gap-2 flex-1 min-w-0">
+										<p className="font-mono text-sm truncate">{record.name}</p>
+										<p className="font-mono text-sm truncate opacity-70 sm:opacity-100">
+											{record.value}
+										</p>
 									</div>
 								</div>
 								<Form method="POST">
-									<input type="hidden" name="action_id" value="remove_record" />
-									<input type="hidden" name="record_name" value={record.name} />
-									<input type="hidden" name="record_type" value={record.type} />
+									<input name="action_id" type="hidden" value="remove_record" />
+									<input name="record_name" type="hidden" value={record.name} />
+									<input name="record_type" type="hidden" value={record.type} />
 									<Button
-										type="submit"
-										isDisabled={isDisabled}
 										className={cn(
 											'px-2 py-1 rounded-md',
 											'text-red-500 dark:text-red-400',
 										)}
+										isDisabled={isDisabled}
+										type="submit"
 									>
 										Remove
 									</Button>

app/routes/dns/components/rename-tailnet.tsx

@@ -9,21 +9,21 @@ interface Props {
 
 export default function RenameTailnet({ name, isDisabled }: Props) {
 	return (
-		<div className="flex flex-col w-2/3 gap-y-4">
+		<div className="flex flex-col w-full sm:w-2/3 gap-y-4">
 			<h1 className="text-2xl font-medium mb-2">Tailnet Name</h1>
 			<p>
 				This is the base domain name of your Tailnet. Devices are accessible at{' '}
 				<Code>[device].{name}</Code> when Magic DNS is enabled.
 			</p>
 			<Input
-				isReadOnly
-				labelHidden
 				className="w-3/5 font-medium text-sm"
+				isReadOnly
 				label="Tailnet name"
-				value={name}
+				labelHidden
 				onFocus={(event) => {
 					event.target.select();
 				}}
+				value={name}
 			/>
 			<Dialog>
 				<Dialog.Button isDisabled={isDisabled}>Rename Tailnet</Dialog.Button>
@@ -33,13 +33,13 @@ export default function RenameTailnet({ name, isDisabled }: Props) {
 						Keep in mind that changing this can lead to all sorts of unexpected
 						behavior and may break existing devices in your tailnet.
 					</Dialog.Text>
-					<input type="hidden" name="action_id" value="rename_tailnet" />
+					<input name="action_id" type="hidden" value="rename_tailnet" />
 					<Input
+						defaultValue={name}
 						isRequired
 						label="Tailnet name"
-						placeholder="ts.net"
-						defaultValue={name}
 						name="new_name"
+						placeholder="ts.net"
 					/>
 				</Dialog.Panel>
 			</Dialog>

app/routes/dns/dns-actions.ts

@@ -1,11 +1,8 @@
-import { ActionFunctionArgs, data } from 'react-router';
-import { LoadContext } from '~/server';
+import { data } from 'react-router';
 import { Capabilities } from '~/server/web/roles';
+import type { Route } from './+types/overview';
 
-export async function dnsAction({
-	request,
-	context,
-}: ActionFunctionArgs<LoadContext>) {
+export async function dnsAction({ request, context }: Route.ActionArgs) {
 	const check = await context.sessions.check(
 		request,
 		Capabilities.write_network,
@@ -19,6 +16,9 @@ export async function dnsAction({
 		return data({ success: false }, 403);
 	}
 
+	// We only need it for health checks which don't require auth
+	const api = context.hsApi.getRuntimeClient('fake-api-key');
+
 	const formData = await request.formData();
 	const action = formData.get('action_id')?.toString();
 	if (!action) {
@@ -26,226 +26,206 @@ export async function dnsAction({
 	}
 
 	switch (action) {
-		case 'rename_tailnet':
-			return renameTailnet(formData, context);
-		case 'toggle_magic':
-			return toggleMagic(formData, context);
-		case 'remove_ns':
-			return removeNs(formData, context);
-		case 'add_ns':
-			return addNs(formData, context);
-		case 'remove_domain':
-			return removeDomain(formData, context);
-		case 'add_domain':
-			return addDomain(formData, context);
-		case 'remove_record':
-			return removeRecord(formData, context);
-		case 'add_record':
-			return addRecord(formData, context);
-		case 'override_dns':
-			return overrideDns(formData, context);
+		case 'rename_tailnet': {
+			const newName = formData.get('new_name')?.toString();
+			if (!newName) {
+				return data({ success: false }, 400);
+			}
+
+			await context.hs.patch([
+				{
+					path: 'dns.base_domain',
+					value: newName,
+				},
+			]);
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'Tailnet renamed successfully' };
+		}
+		case 'toggle_magic': {
+			const newState = formData.get('new_state')?.toString();
+			if (!newState) {
+				return data({ success: false }, 400);
+			}
+
+			await context.hs.patch([
+				{
+					path: 'dns.magic_dns',
+					value: newState === 'enabled',
+				},
+			]);
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'Magic DNS state updated successfully' };
+		}
+		case 'remove_ns': {
+			const config = context.hs.c!;
+			const ns = formData.get('ns')?.toString();
+			const splitName = formData.get('split_name')?.toString();
+
+			if (!ns || !splitName) {
+				return data({ success: false }, 400);
+			}
+
+			if (splitName === 'global') {
+				const servers = config.dns.nameservers.global.filter((i) => i !== ns);
+
+				await context.hs.patch([
+					{
+						path: 'dns.nameservers.global',
+						value: servers,
+					},
+				]);
+			} else {
+				const splits = config.dns.nameservers.split;
+				const servers = splits[splitName].filter((i) => i !== ns);
+
+				await context.hs.patch([
+					{
+						path: `dns.nameservers.split."${splitName}"`,
+						value: servers.length > 0 ? servers : null,
+					},
+				]);
+			}
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'Nameserver removed successfully' };
+		}
+		case 'add_ns': {
+			const config = context.hs.c!;
+			const ns = formData.get('ns')?.toString();
+			const splitName = formData.get('split_name')?.toString();
+
+			if (!ns || !splitName) {
+				return data({ success: false }, 400);
+			}
+
+			if (splitName === 'global') {
+				const servers = config.dns.nameservers.global;
+				servers.push(ns);
+
+				await context.hs.patch([
+					{
+						path: 'dns.nameservers.global',
+						value: servers,
+					},
+				]);
+			} else {
+				const splits = config.dns.nameservers.split;
+				const servers = splits[splitName] ?? [];
+				servers.push(ns);
+
+				await context.hs.patch([
+					{
+						path: `dns.nameservers.split."${splitName}"`,
+						value: servers,
+					},
+				]);
+			}
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'Nameserver added successfully' };
+		}
+		case 'remove_domain': {
+			const config = context.hs.c!;
+			const domain = formData.get('domain')?.toString();
+			if (!domain) {
+				return data({ success: false }, 400);
+			}
+
+			const domains = config.dns.search_domains.filter((i) => i !== domain);
+			await context.hs.patch([
+				{
+					path: 'dns.search_domains',
+					value: domains,
+				},
+			]);
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'Domain removed successfully' };
+		}
+		case 'add_domain': {
+			const config = context.hs.c!;
+			const domain = formData.get('domain')?.toString();
+			if (!domain) {
+				return data({ success: false }, 400);
+			}
+
+			const domains = config.dns.search_domains;
+			domains.push(domain);
+
+			await context.hs.patch([
+				{
+					path: 'dns.search_domains',
+					value: domains,
+				},
+			]);
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'Domain added successfully' };
+		}
+		case 'remove_record': {
+			const recordName = formData.get('record_name')?.toString();
+			const recordType = formData.get('record_type')?.toString();
+
+			if (!recordName || !recordType) {
+				return data({ success: false }, 400);
+			}
+
+			// Value is not needed for removal
+			const restart = await context.hs.removeDNS({
+				name: recordName,
+				type: recordType,
+				value: '',
+			});
+
+			if (!restart) {
+				return;
+			}
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'DNS record removed successfully' };
+		}
+		case 'add_record': {
+			const recordName = formData.get('record_name')?.toString();
+			const recordType = formData.get('record_type')?.toString();
+			const recordValue = formData.get('record_value')?.toString();
+
+			if (!recordName || !recordType || !recordValue) {
+				return data({ success: false }, 400);
+			}
+
+			const restart = await context.hs.addDNS({
+				name: recordName,
+				type: recordType,
+				value: recordValue,
+			});
+
+			if (!restart) {
+				return;
+			}
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'DNS record added successfully' };
+		}
+		case 'override_dns': {
+			const override = formData.get('override_dns')?.toString();
+			if (!override) {
+				return data({ success: false }, 400);
+			}
+
+			const overrideValue = override === 'true';
+			await context.hs.patch([
+				{
+					path: 'dns.override_local_dns',
+					value: overrideValue,
+				},
+			]);
+
+			await context.integration?.onConfigChange(api);
+			return { message: 'DNS override updated successfully' };
+		}
 		default:
 			return data({ success: false }, 400);
 	}
 }
-
-async function renameTailnet(formData: FormData, context: LoadContext) {
-	const newName = formData.get('new_name')?.toString();
-	if (!newName) {
-		return data({ success: false }, 400);
-	}
-
-	await context.hs.patch([
-		{
-			path: 'dns.base_domain',
-			value: newName,
-		},
-	]);
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function toggleMagic(formData: FormData, context: LoadContext) {
-	const newState = formData.get('new_state')?.toString();
-	if (!newState) {
-		return data({ success: false }, 400);
-	}
-
-	await context.hs.patch([
-		{
-			path: 'dns.magic_dns',
-			value: newState === 'enabled',
-		},
-	]);
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function removeNs(formData: FormData, context: LoadContext) {
-	const config = context.hs.c!;
-	const ns = formData.get('ns')?.toString();
-	const splitName = formData.get('split_name')?.toString();
-
-	if (!ns || !splitName) {
-		return data({ success: false }, 400);
-	}
-
-	if (splitName === 'global') {
-		const servers = config.dns.nameservers.global.filter((i) => i !== ns);
-
-		await context.hs.patch([
-			{
-				path: 'dns.nameservers.global',
-				value: servers,
-			},
-		]);
-	} else {
-		const splits = config.dns.nameservers.split;
-		const servers = splits[splitName].filter((i) => i !== ns);
-
-		await context.hs.patch([
-			{
-				path: `dns.nameservers.split."${splitName}"`,
-				value: servers.length > 0 ? servers : null,
-			},
-		]);
-	}
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function addNs(formData: FormData, context: LoadContext) {
-	const config = context.hs.c!;
-	const ns = formData.get('ns')?.toString();
-	const splitName = formData.get('split_name')?.toString();
-
-	if (!ns || !splitName) {
-		return data({ success: false }, 400);
-	}
-
-	if (splitName === 'global') {
-		const servers = config.dns.nameservers.global;
-		servers.push(ns);
-
-		await context.hs.patch([
-			{
-				path: 'dns.nameservers.global',
-				value: servers,
-			},
-		]);
-	} else {
-		const splits = config.dns.nameservers.split;
-		const servers = splits[splitName] ?? [];
-		servers.push(ns);
-
-		await context.hs.patch([
-			{
-				path: `dns.nameservers.split."${splitName}"`,
-				value: servers,
-			},
-		]);
-	}
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function removeDomain(formData: FormData, context: LoadContext) {
-	const config = context.hs.c!;
-	const domain = formData.get('domain')?.toString();
-	if (!domain) {
-		return data({ success: false }, 400);
-	}
-
-	const domains = config.dns.search_domains.filter((i) => i !== domain);
-	await context.hs.patch([
-		{
-			path: 'dns.search_domains',
-			value: domains,
-		},
-	]);
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function addDomain(formData: FormData, context: LoadContext) {
-	const config = context.hs.c!;
-	const domain = formData.get('domain')?.toString();
-	if (!domain) {
-		return data({ success: false }, 400);
-	}
-
-	const domains = config.dns.search_domains;
-	domains.push(domain);
-
-	await context.hs.patch([
-		{
-			path: 'dns.search_domains',
-			value: domains,
-		},
-	]);
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function removeRecord(formData: FormData, context: LoadContext) {
-	const config = context.hs.c!;
-	const recordName = formData.get('record_name')?.toString();
-	const recordType = formData.get('record_type')?.toString();
-
-	if (!recordName || !recordType) {
-		return data({ success: false }, 400);
-	}
-
-	// Value is not needed for removal
-	const restart = await context.hs.removeDNS({
-		name: recordName,
-		type: recordType,
-		value: '',
-	});
-
-	if (!restart) {
-		return;
-	}
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function addRecord(formData: FormData, context: LoadContext) {
-	const config = context.hs.c!;
-	const recordName = formData.get('record_name')?.toString();
-	const recordType = formData.get('record_type')?.toString();
-	const recordValue = formData.get('record_value')?.toString();
-
-	if (!recordName || !recordType || !recordValue) {
-		return data({ success: false }, 400);
-	}
-
-	const restart = await context.hs.addDNS({
-		name: recordName,
-		type: recordType,
-		value: recordValue,
-	});
-
-	if (!restart) {
-		return;
-	}
-
-	await context.integration?.onConfigChange(context.client);
-}
-
-async function overrideDns(formData: FormData, context: LoadContext) {
-	const override = formData.get('override_dns')?.toString();
-	if (!override) {
-		return data({ success: false }, 400);
-	}
-
-	const overrideValue = override === 'true';
-	await context.hs.patch([
-		{
-			path: 'dns.override_local_dns',
-			value: overrideValue,
-		},
-	]);
-
-	await context.integration?.onConfigChange(context.client);
-}

app/routes/dns/overview.tsx

@@ -84,20 +84,20 @@ export default function Page() {
 					tailnet.
 				</Notice>
 			)}
-			<RenameTailnet name={data.baseDomain} isDisabled={isDisabled} />
+			<RenameTailnet isDisabled={isDisabled} name={data.baseDomain} />
 			<ManageNS
-				nameservers={allNs}
 				isDisabled={isDisabled}
+				nameservers={allNs}
 				overrideLocalDns={data.overrideDns}
 			/>
-			<ManageRecords records={data.extraRecords} isDisabled={isDisabled} />
+			<ManageRecords isDisabled={isDisabled} records={data.extraRecords} />
 			<ManageDomains
-				searchDomains={data.searchDomains}
 				isDisabled={isDisabled}
 				magic={data.magicDns ? data.baseDomain : undefined}
+				searchDomains={data.searchDomains}
 			/>
 
-			<div className="flex flex-col w-2/3">
+			<div className="flex flex-col w-full sm:w-2/3">
 				<h1 className="text-2xl font-medium mb-4">Magic DNS</h1>
 				<p className="mb-4">
 					Automatically register domain names for each device on the tailnet.
@@ -108,7 +108,7 @@ export default function Page() {
 					</Code>{' '}
 					when Magic DNS is enabled.
 				</p>
-				<ToggleMagic isEnabled={data.magicDns} isDisabled={isDisabled} />
+				<ToggleMagic isDisabled={isDisabled} isEnabled={data.magicDns} />
 			</div>
 		</div>
 	);

app/routes/machines/components/machine-row.tsx

@@ -13,6 +13,7 @@ import type { User } from '~/types';
 import cn from '~/utils/cn';
 import * as hinfo from '~/utils/host-info';
 import { PopulatedNode } from '~/utils/node-info';
+import { formatTimeDelta } from '~/utils/time';
 import toast from '~/utils/toast';
 import MenuOptions from './menu';
 
@@ -22,6 +23,7 @@ interface Props {
 	isAgent?: boolean;
 	magic?: string;
 	isDisabled?: boolean;
+	existingTags?: string[];
 }
 
 export default function MachineRow({
@@ -30,11 +32,9 @@ export default function MachineRow({
 	isAgent,
 	magic,
 	isDisabled,
+	existingTags,
 }: Props) {
-	const uiTags = useMemo(() => {
-		const tags = uiTagsForNode(node, isAgent);
-		return tags;
-	}, [node, isAgent]);
+	const uiTags = useMemo(() => uiTagsForNode(node, isAgent), [node, isAgent]);
 
 	const ipOptions = useMemo(() => {
 		if (magic) {
@@ -64,7 +64,10 @@ export default function MachineRow({
 						{node.givenName}
 					</p>
 					<p className="text-sm opacity-50">
-						{node.user.name || node.user.displayName || node.user.email || node.user.id}
+						{node.user.name ||
+							node.user.displayName ||
+							node.user.email ||
+							node.user.id}
 					</p>
 					<div className="flex gap-1 flex-wrap mt-1.5">
 						{mapTagsToComponents(node, uiTags)}
@@ -124,25 +127,34 @@ export default function MachineRow({
 				</td>
 			) : undefined}
 			<td className="py-2">
-				<span
-					className={cn(
-						'flex items-center gap-x-1 text-sm',
-						'text-headplane-600 dark:text-headplane-300',
-					)}
-				>
+				<div className="flex items-start gap-x-1">
 					<StatusCircle
-						className="w-4 h-4"
+						className="w-4 h-4 mt-0.5"
 						isOnline={node.online && !node.expired}
 					/>
-					<p suppressHydrationWarning>
-						{node.online && !node.expired
-							? 'Connected'
-							: new Date(node.lastSeen).toLocaleString()}
-					</p>
-				</span>
+					<div>
+						<p
+							className={cn(
+								'text-sm',
+								'text-headplane-600 dark:text-headplane-300',
+							)}
+							suppressHydrationWarning
+						>
+							{node.online && !node.expired
+								? 'Connected'
+								: new Date(node.lastSeen).toLocaleString()}
+						</p>
+						{!(node.online && !node.expired) && (
+							<p className="text-xs opacity-50" suppressHydrationWarning>
+								{formatTimeDelta(new Date(node.lastSeen))}
+							</p>
+						)}
+					</div>
+				</div>
 			</td>
 			<td className="py-2 pr-0.5">
 				<MenuOptions
+					existingTags={existingTags}
 					isDisabled={isDisabled}
 					magic={magic}
 					node={node}

app/routes/machines/components/menu.tsx

@@ -11,12 +11,14 @@ import Move from '../dialogs/move';
 import Rename from '../dialogs/rename';
 import Routes from '../dialogs/routes';
 import Tags from '../dialogs/tags';
+
 interface MenuProps {
 	node: PopulatedNode;
 	users: User[];
 	magic?: string;
 	isFullButton?: boolean;
 	isDisabled?: boolean;
+	existingTags?: string[];
 }
 
 type Modal = 'rename' | 'expire' | 'remove' | 'routes' | 'move' | 'tags' | null;
@@ -27,6 +29,7 @@ export default function MachineMenu({
 	users,
 	isFullButton,
 	isDisabled,
+	existingTags,
 }: MenuProps) {
 	const [modal, setModal] = useState<Modal>(null);
 	const supportsTailscaleSSH =
@@ -36,8 +39,8 @@ export default function MachineMenu({
 		<div className="flex items-center justify-end px-4 gap-1.5">
 			{modal === 'remove' && (
 				<Delete
-					machine={node}
 					isOpen={modal === 'remove'}
+					machine={node}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
@@ -45,19 +48,19 @@ export default function MachineMenu({
 			)}
 			{modal === 'move' && (
 				<Move
-					machine={node}
-					users={users}
 					isOpen={modal === 'move'}
+					machine={node}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
+					users={users}
 				/>
 			)}
 			{modal === 'rename' && (
 				<Rename
+					isOpen={modal === 'rename'}
 					machine={node}
 					magic={magic}
-					isOpen={modal === 'rename'}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
@@ -65,8 +68,8 @@ export default function MachineMenu({
 			)}
 			{modal === 'routes' && (
 				<Routes
-					node={node}
 					isOpen={modal === 'routes'}
+					node={node}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
@@ -74,8 +77,9 @@ export default function MachineMenu({
 			)}
 			{modal === 'tags' && (
 				<Tags
-					machine={node}
+					existingTags={existingTags}
 					isOpen={modal === 'tags'}
+					machine={node}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
@@ -83,8 +87,8 @@ export default function MachineMenu({
 			)}
 			{node.expired && modal === 'expire' ? undefined : (
 				<Expire
-					machine={node}
 					isOpen={modal === 'expire'}
+					machine={node}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
@@ -95,33 +99,23 @@ export default function MachineMenu({
 				isFullButton ? (
 					<Button
 						className="flex items-center gap-x-2"
-						variant="heavy"
 						onPress={() => {
 							// We need to use JS to open the SSH URL
 							// in a new WINDOW since href can only
 							// do a new TAB.
 							window.open(
-								`${__PREFIX__}/ssh?hostname=${node.name}`,
+								`${__PREFIX__}/ssh?hostname=${node.givenName}`,
 								'_blank',
 								'noopener,noreferrer,width=800,height=600',
 							);
 						}}
+						variant="heavy"
 					>
 						<SquareTerminal className="h-5" />
 						<p>SSH</p>
 					</Button>
 				) : (
 					<Button
-						onPress={() => {
-							// We need to use JS to open the SSH URL
-							// in a new WINDOW since href can only
-							// do a new TAB.
-							window.open(
-								`${__PREFIX__}/ssh?hostname=${node.name}`,
-								'_blank',
-								'noopener,noreferrer,width=800,height=600',
-							);
-						}}
 						className={cn(
 							'py-0.5 w-fit bg-transparent border-transparent',
 							'border group-hover:border-headplane-200',
@@ -129,6 +123,16 @@ export default function MachineMenu({
 							'opacity-0 pointer-events-none group-hover:opacity-100',
 							'group-hover:pointer-events-auto',
 						)}
+						onPress={() => {
+							// We need to use JS to open the SSH URL
+							// in a new WINDOW since href can only
+							// do a new TAB.
+							window.open(
+								`${__PREFIX__}/ssh?hostname=${node.givenName}`,
+								'_blank',
+								'noopener,noreferrer,width=800,height=600',
+							);
+						}}
 					>
 						SSH
 					</Button>
@@ -142,19 +146,19 @@ export default function MachineMenu({
 					</Menu.Button>
 				) : (
 					<Menu.IconButton
-						label="Machine Options"
 						className={cn(
 							'py-0.5 w-10 bg-transparent border-transparent',
 							'border group-hover:border-headplane-200',
 							'dark:group-hover:border-headplane-700',
 						)}
+						label="Machine Options"
 					>
 						<Ellipsis className="h-5" />
 					</Menu.IconButton>
 				)}
 				<Menu.Panel
-					onAction={(key) => setModal(key as Modal)}
 					disabledKeys={node.expired ? ['expire'] : []}
+					onAction={(key) => setModal(key as Modal)}
 				>
 					<Menu.Section>
 						<Menu.Item key="rename">Edit machine name</Menu.Item>

app/routes/machines/dialogs/delete.tsx

@@ -14,16 +14,16 @@ export default function Delete({ machine, isOpen, setIsOpen }: DeleteProps) {
 	return (
 		<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
 			<Dialog.Panel
-				variant="destructive"
 				onSubmit={() => navigate('/machines')}
+				variant="destructive"
 			>
 				<Dialog.Title>Remove {machine.givenName}</Dialog.Title>
 				<Dialog.Text>
 					This machine will be permanently removed from your network. To re-add
 					it, you will need to reauthenticate to your tailnet from the device.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="delete" />
-				<input type="hidden" name="node_id" value={machine.id} />
+				<input name="action_id" type="hidden" value="delete" />
+				<input name="node_id" type="hidden" value={machine.id} />
 			</Dialog.Panel>
 		</Dialog>
 	);

app/routes/machines/dialogs/move.tsx

@@ -11,30 +11,32 @@ interface MoveProps {
 }
 
 export default function Move({ machine, users, isOpen, setIsOpen }: MoveProps) {
-	const [userId, setUserId] = useState<Key | null>(null);
+	const [userId, setUserId] = useState<Key | null>(machine.user.id);
 
 	return (
 		<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
-			<Dialog.Panel>
+			<Dialog.Panel isDisabled={userId === machine.user.id}>
 				<Dialog.Title>Change the owner of {machine.givenName}</Dialog.Title>
 				<Dialog.Text>
 					The owner of the machine is the user associated with it.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="reassign" />
-				<input type="hidden" name="node_id" value={machine.id} />
-				<input type="hidden" name="user_id" value={userId?.toString()} />
+				<input name="action_id" type="hidden" value="reassign" />
+				<input name="node_id" type="hidden" value={machine.id} />
+				<input name="user_id" type="hidden" value={userId?.toString()} />
 				<Select
+					defaultSelectedKey={machine.user.id}
 					isRequired
 					label="Owner"
 					name="user"
-					placeholder="Select a user"
-					defaultSelectedKey={machine.user.id}
 					onSelectionChange={(key) => {
 						setUserId(key);
 					}}
+					placeholder="Select a user"
 				>
 					{users.map((user) => (
-					    <Select.Item key={user.id}>{user.name || user.displayName || user.email || user.id}</Select.Item>
+						<Select.Item key={user.id}>
+							{user.name || user.displayName || user.email || user.id}
+						</Select.Item>
 					))}
 				</Select>
 			</Dialog.Panel>

app/routes/machines/dialogs/new.tsx

@@ -20,24 +20,28 @@ export default function NewMachine(data: NewMachineProps) {
 	const [mkey, setMkey] = useState('');
 	const navigate = useNavigate();
 
+	const isMkeyInvalid = mkey.length > 0 && mkey.length !== 24;
+
 	return (
 		<>
 			<Dialog isOpen={pushDialog} onOpenChange={setPushDialog}>
-				<Dialog.Panel isDisabled={mkey.length < 1}>
+				<Dialog.Panel isDisabled={mkey.length !== 24}>
 					<Dialog.Title>Register Machine Key</Dialog.Title>
 					<Dialog.Text className="mb-4">
 						The machine key is given when you run{' '}
 						<Code isCopyable>tailscale up --login-server={data.server}</Code> on
 						your device.
 					</Dialog.Text>
-					<input type="hidden" name="action_id" value="register" />
+					<input name="action_id" type="hidden" value="register" />
 					<Input
+						errorMessage="Machine key must be exactly 24 characters"
+						isInvalid={isMkeyInvalid}
 						isRequired
 						label="Machine Key"
-						placeholder="AbCd..."
-						validationBehavior="native"
 						name="register_key"
 						onChange={setMkey}
+						placeholder="AbCd..."
+						validationBehavior="native"
 					/>
 					<Select
 						isRequired
@@ -46,12 +50,14 @@ export default function NewMachine(data: NewMachineProps) {
 						placeholder="Select a user"
 					>
 						{data.users.map((user) => (
-						    <Select.Item key={user.id}>{user.name || user.displayName || user.email || user.id}</Select.Item>
+							<Select.Item key={user.id}>
+								{user.name || user.displayName || user.email || user.id}
+							</Select.Item>
 						))}
 					</Select>
 				</Dialog.Panel>
 			</Dialog>
-			<Menu isDisabled={data.isDisabled} disabledKeys={data.disabledKeys}>
+			<Menu disabledKeys={data.disabledKeys} isDisabled={data.isDisabled}>
 				<Menu.Button variant="heavy">Add Device</Menu.Button>
 				<Menu.Panel
 					onAction={(key) => {

app/routes/machines/dialogs/rename.tsx

@@ -27,16 +27,15 @@ export default function Rename({
 					This name is shown in the admin panel, in Tailscale clients, and used
 					when generating MagicDNS names.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="rename" />
-				<input type="hidden" name="node_id" value={machine.id} />
+				<input name="action_id" type="hidden" value="rename" />
+				<input name="node_id" type="hidden" value={machine.id} />
 				<Input
+					defaultValue={machine.givenName}
 					isRequired
 					label="Machine name"
-					placeholder="Machine name"
-					validationBehavior="native"
 					name="name"
-					defaultValue={machine.givenName}
 					onChange={setName}
+					placeholder="Machine name"
 					validate={(value) => {
 						if (value.length === 0) {
 							return 'Cannot be empty';
@@ -66,6 +65,7 @@ export default function Rename({
 							return 'Cannot contain consecutive hyphens';
 						}
 					}}
+					validationBehavior="native"
 				/>
 				{magic ? (
 					name.length > 0 && name !== machine.givenName ? (

app/routes/machines/dialogs/routes.tsx

@@ -30,8 +30,8 @@ export default function Routes({ node, isOpen, setIsOpen }: RoutesProps) {
 					Connect to devices you can't install Tailscale on by advertising
 					IP ranges as subnet routes.{' '}
 					<Link
-						to="https://tailscale.com/kb/1019/subnets"
 						name="Tailscale Subnets Documentation"
+						to="https://tailscale.com/kb/1019/subnets"
 					>
 						Learn More
 					</Link>
@@ -70,8 +70,8 @@ export default function Routes({ node, isOpen, setIsOpen }: RoutesProps) {
 				<Dialog.Text>
 					Allow your network to route internet traffic through this machine.{' '}
 					<Link
-						to="https://tailscale.com/kb/1103/exit-nodes"
 						name="Tailscale Exit-node Documentation"
+						to="https://tailscale.com/kb/1103/exit-nodes"
 					>
 						Learn More
 					</Link>

app/routes/machines/dialogs/tags.tsx

@@ -1,9 +1,9 @@
 import { Plus, TagsIcon, X } from 'lucide-react';
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import Button from '~/components/Button';
 import Dialog from '~/components/Dialog';
-import Input from '~/components/Input';
 import Link from '~/components/Link';
+import Select from '~/components/Select';
 import TableList from '~/components/TableList';
 import type { Machine } from '~/types';
 import cn from '~/utils/cn';
@@ -12,11 +12,24 @@ interface TagsProps {
 	machine: Machine;
 	isOpen: boolean;
 	setIsOpen: (isOpen: boolean) => void;
+	existingTags?: string[];
 }
 
-export default function Tags({ machine, isOpen, setIsOpen }: TagsProps) {
+export default function Tags({
+	machine,
+	isOpen,
+	setIsOpen,
+	existingTags,
+}: TagsProps) {
 	const [tags, setTags] = useState(machine.forcedTags);
-	const [tag, setTag] = useState('');
+	const [tag, setTag] = useState('tag:');
+	const tagIsInvalid = useMemo(() => {
+		return tag.length === 0 || !tag.startsWith('tag:') || tags.includes(tag);
+	}, [tag, tags]);
+
+	const validNodeTags = useMemo(() => {
+		return existingTags?.filter((nodeTag) => !tags.includes(nodeTag)) || [];
+	}, [tags]);
 
 	return (
 		<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
@@ -26,16 +39,16 @@ export default function Tags({ machine, isOpen, setIsOpen }: TagsProps) {
 					ACL tags can be used to reference machines in your ACL policies. See
 					the{' '}
 					<Link
-						to="https://tailscale.com/kb/1068/acl-tags"
 						name="Tailscale documentation"
+						to="https://tailscale.com/kb/1068/acl-tags"
 					>
 						Tailscale documentation
 					</Link>{' '}
 					for more information.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="update_tags" />
-				<input type="hidden" name="node_id" value={machine.id} />
-				<input type="hidden" name="tags" value={tags.join(',')} />
+				<input name="action_id" type="hidden" value="update_tags" />
+				<input name="node_id" type="hidden" value={machine.id} />
+				<input name="tags" type="hidden" value={tags.join(',')} />
 				<TableList className="mt-4">
 					{tags.length === 0 ? (
 						<TableList.Item className="flex flex-col items-center gap-2.5 py-4 opacity-70">
@@ -44,7 +57,7 @@ export default function Tags({ machine, isOpen, setIsOpen }: TagsProps) {
 						</TableList.Item>
 					) : (
 						tags.map((item) => (
-							<TableList.Item className="font-mono" key={item} id={item}>
+							<TableList.Item className="font-mono" id={item} key={item}>
 								{item}
 								<Button
 									className="rounded-md p-0.5"
@@ -57,44 +70,36 @@ export default function Tags({ machine, isOpen, setIsOpen }: TagsProps) {
 							</TableList.Item>
 						))
 					)}
-					<TableList.Item
-						className={cn(
-							'rounded-b-xl focus-within:ring-3',
-							tag.length > 0 &&
-								(!tag.startsWith('tag:') || tags.includes(tag)) &&
-								'ring-3 ring-red-500 ring-opacity-50',
-						)}
-					>
-						<Input
-							labelHidden
-							label="Add a tag"
-							placeholder="tag:example"
-							onChange={setTag}
-							className={cn(
-								'border-none font-mono p-0',
-								'rounded-none focus:ring-0 w-full',
-							)}
-						/>
-						<Button
-							className={cn(
-								'rounded-md p-0.5',
-								(!tag.startsWith('tag:') || tags.includes(tag)) &&
-									'opacity-50 cursor-not-allowed',
-							)}
-							isDisabled={
-								tag.length === 0 ||
-								!tag.startsWith('tag:') ||
-								tags.includes(tag)
-							}
-							onPress={() => {
-								setTags([...tags, tag]);
-								setTag('');
-							}}
-						>
-							<Plus className="p-1" />
-						</Button>
-					</TableList.Item>
 				</TableList>
+
+				<div className="flex items-center gap-2 mt-2">
+					<Select
+						allowsCustomValue
+						aria-label="Add a tag"
+						className="w-full"
+						inputValue={tag}
+						isInvalid={tag.length > 0 && tagIsInvalid}
+						onInputChange={setTag}
+						placeholder="tag:example"
+					>
+						{validNodeTags.map((nodeTag) => {
+							return <Select.Item key={nodeTag}>{nodeTag}</Select.Item>;
+						})}
+					</Select>
+					<Button
+						className={cn(
+							'rounded-md p-1',
+							tagIsInvalid && 'opacity-50 cursor-not-allowed',
+						)}
+						isDisabled={tagIsInvalid}
+						onPress={() => {
+							setTags([...tags, tag]);
+							setTag('tag:');
+						}}
+					>
+						<Plus className="p-1" size={30} />
+					</Button>
+				</div>
 			</Dialog.Panel>
 		</Dialog>
 	);

app/routes/machines/machine-actions.ts

@@ -1,12 +1,8 @@
-import { type ActionFunctionArgs, data, redirect } from 'react-router';
-import type { LoadContext } from '~/server';
+import { data, redirect } from 'react-router';
 import { Capabilities } from '~/server/web/roles';
-import { Machine } from '~/types';
+import type { Route } from './+types/machine';
 
-export async function machineAction({
-	request,
-	context,
-}: ActionFunctionArgs<LoadContext>) {
+export async function machineAction({ request, context }: Route.ActionArgs) {
 	const session = await context.sessions.auth(request);
 	const check = await context.sessions.check(
 		request,
@@ -14,7 +10,7 @@ export async function machineAction({
 	);
 
 	const formData = await request.formData();
-	const apiKey = session.api_key;
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 
 	const action = formData.get('action_id')?.toString();
 	if (!action) {
@@ -31,7 +27,22 @@ export async function machineAction({
 			});
 		}
 
-		return registerMachine(formData, apiKey, context);
+		const registrationKey = formData.get('register_key')?.toString();
+		if (!registrationKey) {
+			throw data('Missing `register_key` in the form data.', {
+				status: 400,
+			});
+		}
+
+		const user = formData.get('user')?.toString();
+		if (!user) {
+			throw data('Missing `user` in the form data.', {
+				status: 400,
+			});
+		}
+
+		const node = await api.registerNode(user, registrationKey);
+		return redirect(`/machines/${node.id}`);
 	}
 
 	// Check if the user has permission to manage this machine
@@ -42,12 +53,7 @@ export async function machineAction({
 		});
 	}
 
-	const { nodes } = await context.client.get<{ nodes: Machine[] }>(
-		'v1/node',
-		apiKey,
-	);
-
-	const node = nodes.find((node) => node.id === nodeId);
+	const node = await api.getNode(nodeId);
 	if (!node) {
 		throw data(`Machine with ID ${nodeId} not found`, {
 			status: 404,
@@ -65,27 +71,103 @@ export async function machineAction({
 
 	switch (action) {
 		case 'rename': {
-			return renameMachine(formData, apiKey, nodeId, context);
+			const newName = formData.get('name')?.toString();
+			if (!newName) {
+				throw data('Missing `name` in the form data.', {
+					status: 400,
+				});
+			}
+
+			const name = String(formData.get('name'));
+			await api.renameNode(nodeId, name);
+			return { message: 'Machine renamed' };
 		}
 
 		case 'delete': {
-			return deleteMachine(apiKey, nodeId, context);
+			await api.deleteNode(nodeId);
+			return redirect('/machines');
 		}
 
 		case 'expire': {
-			return expireMachine(apiKey, nodeId, context);
+			await api.expireNode(nodeId);
+			return { message: 'Machine expired' };
 		}
 
 		case 'update_tags': {
-			return updateTags(formData, apiKey, nodeId, context);
+			const tags = formData.get('tags')?.toString().split(',') ?? [];
+			if (tags.length === 0) {
+				throw data('Missing `tags` in the form data.', {
+					status: 400,
+				});
+			}
+
+			await api.setNodeTags(
+				nodeId,
+				tags.map((tag) => tag.trim()).filter((tag) => tag !== ''),
+			);
+			return { message: 'Tags updated' };
 		}
 
 		case 'update_routes': {
-			return updateRoutes(formData, apiKey, nodeId, context);
+			const newApproved = node.approvedRoutes;
+			const routes = formData.get('routes')?.toString();
+			if (!routes) {
+				throw data('Missing `routes` in the form data.', {
+					status: 400,
+				});
+			}
+
+			const allRoutes = routes.split(',').map((route) => route.trim());
+			if (allRoutes.length === 0) {
+				throw data('No routes provided to update', {
+					status: 400,
+				});
+			}
+
+			const enabled = formData.get('enabled')?.toString();
+			if (enabled === undefined) {
+				throw data('Missing `enabled` in the form data.', {
+					status: 400,
+				});
+			}
+
+			if (enabled === 'true') {
+				for (const route of allRoutes) {
+					// If already approved, skip, otherwise add to approved
+					if (newApproved.includes(route)) {
+						continue;
+					}
+
+					newApproved.push(route);
+				}
+			} else {
+				for (const route of allRoutes) {
+					// If not approved, skip, otherwise remove from approved
+					if (!newApproved.includes(route)) {
+						continue;
+					}
+
+					const index = newApproved.indexOf(route);
+					if (index > -1) {
+						newApproved.splice(index, 1);
+					}
+				}
+			}
+
+			await api.approveNodeRoutes(nodeId, newApproved);
+			return { message: 'Routes updated' };
 		}
 
 		case 'reassign': {
-			return reassignMachine(formData, apiKey, nodeId, context);
+			const user = formData.get('user_id')?.toString();
+			if (!user) {
+				throw data('Missing `user_id` in the form data.', {
+					status: 400,
+				});
+			}
+
+			await api.setNodeUser(nodeId, user);
+			return { message: 'Machine reassigned' };
 		}
 
 		default:
@@ -94,173 +176,3 @@ export async function machineAction({
 			});
 	}
 }
-
-async function registerMachine(
-	formData: FormData,
-	apiKey: string,
-	context: LoadContext,
-) {
-	const registrationKey = formData.get('register_key')?.toString();
-	if (!registrationKey) {
-		throw data('Missing `register_key` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const user = formData.get('user')?.toString();
-	if (!user) {
-		throw data('Missing `user` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const qp = new URLSearchParams();
-	qp.append('user', user);
-	qp.append('key', registrationKey);
-	const url = `v1/node/register?${qp.toString()}`;
-	const { node } = await context.client.post<{ node: Machine }>(url, apiKey, {
-		user,
-		key: registrationKey,
-	});
-
-	return redirect(`/machines/${node.id}`);
-}
-
-async function renameMachine(
-	formData: FormData,
-	apiKey: string,
-	nodeId: string,
-	context: LoadContext,
-) {
-	const newName = formData.get('name')?.toString();
-	if (!newName) {
-		throw data('Missing `name` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const name = String(formData.get('name'));
-	await context.client.post(`v1/node/${nodeId}/rename/${name}`, apiKey);
-	return { message: 'Machine renamed' };
-}
-
-async function deleteMachine(
-	apiKey: string,
-	nodeId: string,
-	context: LoadContext,
-) {
-	await context.client.delete(`v1/node/${nodeId}`, apiKey);
-	return redirect('/machines');
-}
-
-async function expireMachine(
-	apiKey: string,
-	nodeId: string,
-	context: LoadContext,
-) {
-	await context.client.post(`v1/node/${nodeId}/expire`, apiKey);
-	return { message: 'Machine expired' };
-}
-
-async function updateTags(
-	formData: FormData,
-	apiKey: string,
-	nodeId: string,
-	context: LoadContext,
-) {
-	const tags = formData.get('tags')?.toString().split(',') ?? [];
-	if (tags.length === 0) {
-		throw data('Missing `tags` in the form data.', {
-			status: 400,
-		});
-	}
-
-	await context.client.post(`v1/node/${nodeId}/tags`, apiKey, {
-		tags: tags.map((tag) => tag.trim()).filter((tag) => tag !== ''),
-	});
-
-	return { message: 'Tags updated' };
-}
-
-async function updateRoutes(
-	formData: FormData,
-	apiKey: string,
-	nodeId: string,
-	context: LoadContext,
-) {
-	const { node } = await context.client.get<{ node: Machine }>(
-		`v1/node/${nodeId}`,
-		apiKey,
-	);
-
-	const newApproved = node.approvedRoutes;
-	const routes = formData.get('routes')?.toString();
-	if (!routes) {
-		throw data('Missing `routes` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const allRoutes = routes.split(',').map((route) => route.trim());
-	if (allRoutes.length === 0) {
-		throw data('No routes provided to update', {
-			status: 400,
-		});
-	}
-
-	const enabled = formData.get('enabled')?.toString();
-	if (enabled === undefined) {
-		throw data('Missing `enabled` in the form data.', {
-			status: 400,
-		});
-	}
-
-	if (enabled === 'true') {
-		for (const route of allRoutes) {
-			// If already approved, skip, otherwise add to approved
-			if (newApproved.includes(route)) {
-				continue;
-			}
-
-			newApproved.push(route);
-		}
-	} else {
-		for (const route of allRoutes) {
-			// If not approved, skip, otherwise remove from approved
-			if (!newApproved.includes(route)) {
-				continue;
-			}
-
-			const index = newApproved.indexOf(route);
-			if (index > -1) {
-				newApproved.splice(index, 1);
-			}
-		}
-	}
-
-	await context.client.post(`v1/node/${nodeId}/approve_routes`, apiKey, {
-		routes: newApproved,
-	});
-
-	return { message: 'Routes updated' };
-}
-
-async function reassignMachine(
-	formData: FormData,
-	apiKey: string,
-	nodeId: string,
-	context: LoadContext,
-) {
-	const user = formData.get('user_id')?.toString();
-	if (!user) {
-		throw data('Missing `user_id` in the form data.', {
-			status: 400,
-		});
-	}
-
-	await context.client.post(`v1/node/${nodeId}/user`, apiKey, {
-		user,
-	});
-
-	return { message: 'Machine reassigned' };
-}

app/routes/machines/machine.tsx

@@ -1,7 +1,6 @@
 import { CheckCircle, CircleSlash, Info, UserCircle } from 'lucide-react';
 import { useMemo, useState } from 'react';
-import type { ActionFunctionArgs, LoaderFunctionArgs } from 'react-router';
-import { Link as RemixLink, useLoaderData } from 'react-router';
+import { data, Link as RemixLink } from 'react-router';
 import Attribute from '~/components/Attribute';
 import Button from '~/components/Button';
 import Card from '~/components/Card';
@@ -9,26 +8,25 @@ import Chip from '~/components/Chip';
 import Link from '~/components/Link';
 import StatusCircle from '~/components/StatusCircle';
 import Tooltip from '~/components/Tooltip';
-import type { LoadContext } from '~/server';
-import type { Machine, User } from '~/types';
 import cn from '~/utils/cn';
 import { getOSInfo, getTSVersion } from '~/utils/host-info';
-import { mapNodes } from '~/utils/node-info';
+import { mapNodes, sortNodeTags } from '~/utils/node-info';
+import type { Route } from './+types/machine';
 import { mapTagsToComponents, uiTagsForNode } from './components/machine-row';
 import MenuOptions from './components/menu';
 import Routes from './dialogs/routes';
 import { machineAction } from './machine-actions';
 
-export async function loader({
-	request,
-	params,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, params, context }: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
 	if (!params.id) {
 		throw new Error('No machine ID provided');
 	}
 
+	if (params.id.endsWith('.ico')) {
+		throw data(null, { status: 204 });
+	}
+
 	let magic: string | undefined;
 	if (context.hs.readable()) {
 		if (context.hs.c?.dns.magic_dns) {
@@ -36,37 +34,32 @@ export async function loader({
 		}
 	}
 
-	const [machine, { users }] = await Promise.all([
-		context.client.get<{ node: Machine }>(
-			`v1/node/${params.id}`,
-			session.api_key,
-		),
-		context.client.get<{ users: User[] }>('v1/user', session.api_key),
-	]);
+	const api = context.hsApi.getRuntimeClient(session.api_key);
+	const [nodes, users] = await Promise.all([api.getNodes(), api.getUsers()]);
+	const node = nodes.find((node) => node.id === params.id);
 
-	const lookup = await context.agents?.lookup([machine.node.nodeKey]);
-	const [node] = mapNodes([machine.node], lookup);
+	const lookup = await context.agents?.lookup([node.nodeKey]);
+	const [enhancedNode] = mapNodes([node], lookup);
 	const tags = Array.from(
 		new Set([...node.validTags, ...node.forcedTags]),
 	).sort();
 
 	return {
-		node,
+		node: enhancedNode,
 		tags,
 		users,
 		magic,
 		agent: context.agents?.agentID(),
-		stats: lookup?.[node.nodeKey],
+		stats: lookup?.[enhancedNode.nodeKey],
+		existingTags: sortNodeTags(nodes),
 	};
 }
 
-export async function action(request: ActionFunctionArgs) {
-	return machineAction(request);
-}
+export const action = machineAction;
 
-export default function Page() {
-	const { node, tags, magic, users, agent, stats } =
-		useLoaderData<typeof loader>();
+export default function Page({
+	loaderData: { node, tags, users, magic, agent, stats, existingTags },
+}: Route.ComponentProps) {
 	const [showRouting, setShowRouting] = useState(false);
 
 	const uiTags = useMemo(() => {
@@ -93,7 +86,13 @@ export default function Page() {
 					<h1 className="text-2xl font-medium">{node.givenName}</h1>
 					<StatusCircle className="w-4 h-4" isOnline={node.online} />
 				</span>
-				<MenuOptions isFullButton magic={magic} node={node} users={users} />
+				<MenuOptions
+					existingTags={existingTags}
+					isFullButton
+					magic={magic}
+					node={node}
+					users={users}
+				/>
 			</div>
 			<div className="flex gap-1 mb-4">
 				<div className="border-r border-headplane-100 dark:border-headplane-800 p-2 pr-4">

app/routes/machines/overview.tsx

@@ -1,22 +1,18 @@
-import { Info } from 'lucide-react';
-import type { ActionFunctionArgs, LoaderFunctionArgs } from 'react-router';
-import { useLoaderData } from 'react-router';
+import { ChevronDown, ChevronUp, Info, X } from 'lucide-react';
+import { useMemo, useState } from 'react';
 import Code from '~/components/Code';
+import Input from '~/components/Input';
 import Link from '~/components/Link';
 import Tooltip from '~/components/Tooltip';
-import type { LoadContext } from '~/server';
 import { Capabilities } from '~/server/web/roles';
-import type { Machine, User } from '~/types';
 import cn from '~/utils/cn';
-import { mapNodes } from '~/utils/node-info';
+import { mapNodes, sortNodeTags } from '~/utils/node-info';
+import type { Route } from './+types/overview';
 import MachineRow from './components/machine-row';
 import NewMachine from './dialogs/new';
 import { machineAction } from './machine-actions';
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
 	const user = session.user;
 	if (!user) {
@@ -40,10 +36,8 @@ export async function loader({
 		Capabilities.write_machines,
 	);
 
-	const [{ nodes }, { users }] = await Promise.all([
-		context.client.get<{ nodes: Machine[] }>('v1/node', session.api_key),
-		context.client.get<{ users: User[] }>('v1/user', session.api_key),
-	]);
+	const api = context.hsApi.getRuntimeClient(session.api_key);
+	const [nodes, users] = await Promise.all([api.getNodes(), api.getUsers()]);
 
 	let magic: string | undefined;
 	if (context.hs.readable()) {
@@ -72,17 +66,99 @@ export async function loader({
 	};
 }
 
-export async function action(request: ActionFunctionArgs) {
-	return machineAction(request);
-}
+export const action = machineAction;
 
-export default function Page() {
-	const data = useLoaderData<typeof loader>();
+type SortField = 'name' | 'ip' | 'version' | 'lastSeen';
+
+export default function Page({ loaderData }: Route.ComponentProps) {
+	const [searchQuery, setSearchQuery] = useState('');
+	const [sortField, setSortField] = useState<SortField>('name');
+	const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
+
+	const filteredAndSortedNodes = useMemo(() => {
+		const query = searchQuery.toLowerCase().trim();
+
+		let nodes = loaderData.populatedNodes.filter((node) => {
+			if (!query) return true;
+			if (node.givenName.toLowerCase().includes(query)) return true;
+			if (node.ipAddresses.some((ip) => ip.toLowerCase().includes(query)))
+				return true;
+			return false;
+		});
+
+		nodes = [...nodes].sort((a, b) => {
+			let comparison = 0;
+
+			switch (sortField) {
+				case 'name':
+					comparison = a.givenName.localeCompare(b.givenName);
+					break;
+				case 'ip': {
+					const getIPv4 = (addresses: string[]) =>
+						addresses.find((ip) => !ip.includes(':')) || addresses[0] || '';
+					const ipA = getIPv4(a.ipAddresses);
+					const ipB = getIPv4(b.ipAddresses);
+
+					if (!ipA.includes(':') && !ipB.includes(':')) {
+						const octetsA = ipA.split('.').map(Number);
+						const octetsB = ipB.split('.').map(Number);
+						for (let i = 0; i < 4; i++) {
+							if (octetsA[i] !== octetsB[i]) {
+								comparison = octetsA[i] - octetsB[i];
+								break;
+							}
+						}
+					} else {
+						comparison = ipA.localeCompare(ipB);
+					}
+					break;
+				}
+				case 'version': {
+					const versionA = a.hostInfo?.IPNVersion?.split('-')[0] || '0';
+					const versionB = b.hostInfo?.IPNVersion?.split('-')[0] || '0';
+					const partsA = versionA.split('.').map(Number);
+					const partsB = versionB.split('.').map(Number);
+					const maxLen = Math.max(partsA.length, partsB.length);
+
+					for (let i = 0; i < maxLen; i++) {
+						const segA = partsA[i] || 0;
+						const segB = partsB[i] || 0;
+						if (segA !== segB) {
+							comparison = segA - segB;
+							break;
+						}
+					}
+					break;
+				}
+				case 'lastSeen':
+					if (a.online !== b.online) {
+						comparison = a.online ? 1 : -1;
+						break;
+					}
+					comparison =
+						new Date(a.lastSeen).getTime() - new Date(b.lastSeen).getTime();
+					break;
+			}
+
+			return sortDirection === 'asc' ? comparison : -comparison;
+		});
+
+		return nodes;
+	}, [loaderData.populatedNodes, searchQuery, sortField, sortDirection]);
+
+	const handleSort = (field: SortField) => {
+		if (sortField === field) {
+			setSortDirection((prev) => (prev === 'asc' ? 'desc' : 'asc'));
+		} else {
+			setSortField(field);
+			setSortDirection('asc');
+		}
+	};
 
 	return (
 		<>
-			<div className="flex justify-between items-center mb-6">
-				<div className="flex flex-col w-2/3">
+			<div className="flex flex-col sm:flex-row sm:justify-between sm:items-center gap-4 mb-6">
+				<div className="flex flex-col">
 					<h1 className="text-2xl font-medium mb-2">Machines</h1>
 					<p>
 						Manage the devices connected to your Tailnet.{' '}
@@ -95,63 +171,221 @@ export default function Page() {
 					</p>
 				</div>
 				<NewMachine
-					disabledKeys={data.preAuth ? [] : ['pre-auth']}
-					isDisabled={!data.writable}
-					server={data.publicServer ?? data.server}
-					users={data.users}
+					disabledKeys={loaderData.preAuth ? [] : ['pre-auth']}
+					isDisabled={!loaderData.writable}
+					server={loaderData.publicServer ?? loaderData.server}
+					users={loaderData.users}
 				/>
 			</div>
-			<table className="table-auto w-full rounded-lg">
-				<thead className="text-headplane-600 dark:text-headplane-300">
-					<tr className="text-left px-0.5">
-						<th className="uppercase text-xs font-bold pb-2">Name</th>
-						<th className="pb-2 w-1/4">
-							<div className="flex items-center gap-x-1">
-								<p className="uppercase text-xs font-bold">Addresses</p>
-								{data.magic ? (
-									<Tooltip>
-										<Info className="w-4 h-4" />
-										<Tooltip.Body className="font-normal">
-											Since MagicDNS is enabled, you can access devices based on
-											their name and also at{' '}
-											<Code>
-												[name].
-												{data.magic}
-											</Code>
-										</Tooltip.Body>
-									</Tooltip>
-								) : undefined}
-							</div>
-						</th>
-						{/* We only want to show the version column if there are agents */}
-						{data.agent !== undefined ? (
-							<th className="uppercase text-xs font-bold pb-2">Version</th>
-						) : undefined}
-						<th className="uppercase text-xs font-bold pb-2">Last Seen</th>
-					</tr>
-				</thead>
-				<tbody
-					className={cn(
-						'divide-y divide-headplane-100 dark:divide-headplane-800 align-top',
-						'border-t border-headplane-100 dark:border-headplane-800',
+			<div className="mb-4 flex items-center gap-4">
+				<div className="relative w-64">
+					<Input
+						label="Search machines"
+						labelHidden
+						maxLength={100}
+						onChange={(value) => setSearchQuery(value.slice(0, 100))}
+						placeholder="Search by name or IP address..."
+						value={searchQuery}
+					/>
+					{searchQuery && (
+						<button
+							aria-label="Clear search"
+							className={cn(
+								'absolute right-2 top-1/2 -translate-y-1/2',
+								'p-1 rounded-full',
+								'text-headplane-400 hover:text-headplane-600',
+								'dark:text-headplane-500 dark:hover:text-headplane-300',
+								'hover:bg-headplane-100 dark:hover:bg-headplane-800',
+							)}
+							onClick={() => setSearchQuery('')}
+							type="button"
+						>
+							<X className="w-4 h-4" />
+						</button>
 					)}
-				>
-					{data.populatedNodes.map((machine) => (
-						<MachineRow
-							isAgent={data.agent ? data.agent === machine.nodeKey : undefined}
-							isDisabled={
-								data.writable
-									? false // If the user has write permissions, they can edit all machines
-									: machine.user.providerId?.split('/').pop() !== data.subject
-							}
-							key={machine.id}
-							magic={data.magic}
-							node={machine}
-							users={data.users}
-						/>
-					))}
-				</tbody>
-			</table>
+				</div>
+				<span className="text-sm text-headplane-500 whitespace-nowrap">
+					{searchQuery
+						? `Showing ${filteredAndSortedNodes.length} of ${loaderData.populatedNodes.length} machines`
+						: `${loaderData.populatedNodes.length} machines`}
+				</span>
+			</div>
+			<div className="overflow-x-auto">
+				<table className="table-auto w-full rounded-lg min-w-[640px]">
+					<thead className="text-headplane-600 dark:text-headplane-300">
+						<tr className="text-left px-0.5">
+							<th
+								aria-sort={
+									sortField === 'name'
+										? sortDirection === 'asc'
+											? 'ascending'
+											: 'descending'
+										: 'none'
+								}
+								className="uppercase text-xs font-bold pb-2"
+							>
+								<button
+									aria-label="Sort by name"
+									className={cn(
+										'flex items-center gap-x-1 cursor-pointer',
+										'hover:text-headplane-900 dark:hover:text-headplane-100',
+									)}
+									onClick={() => handleSort('name')}
+									type="button"
+								>
+									Name
+									{sortField === 'name' &&
+										(sortDirection === 'asc' ? (
+											<ChevronUp className="w-3 h-3" />
+										) : (
+											<ChevronDown className="w-3 h-3" />
+										))}
+								</button>
+							</th>
+							<th
+								aria-sort={
+									sortField === 'ip'
+										? sortDirection === 'asc'
+											? 'ascending'
+											: 'descending'
+										: 'none'
+								}
+								className="pb-2 w-1/4"
+							>
+								<div className="flex items-center gap-x-1">
+									<button
+										aria-label="Sort by IP address"
+										className={cn(
+											'flex items-center gap-x-1 cursor-pointer uppercase text-xs font-bold',
+											'hover:text-headplane-900 dark:hover:text-headplane-100',
+										)}
+										onClick={() => handleSort('ip')}
+										type="button"
+									>
+										Addresses
+										{sortField === 'ip' &&
+											(sortDirection === 'asc' ? (
+												<ChevronUp className="w-3 h-3" />
+											) : (
+												<ChevronDown className="w-3 h-3" />
+											))}
+									</button>
+									{loaderData.magic ? (
+										<Tooltip>
+											<Info className="w-4 h-4" />
+											<Tooltip.Body className="font-normal">
+												Since MagicDNS is enabled, you can access devices based
+												on their name and also at{' '}
+												<Code>
+													[name].
+													{loaderData.magic}
+												</Code>
+											</Tooltip.Body>
+										</Tooltip>
+									) : undefined}
+								</div>
+							</th>
+							{/* We only want to show the version column if there are agents */}
+							{loaderData.agent !== undefined ? (
+								<th
+									aria-sort={
+										sortField === 'version'
+											? sortDirection === 'asc'
+												? 'ascending'
+												: 'descending'
+											: 'none'
+									}
+									className="uppercase text-xs font-bold pb-2"
+								>
+									<button
+										aria-label="Sort by version"
+										className={cn(
+											'flex items-center gap-x-1 cursor-pointer',
+											'hover:text-headplane-900 dark:hover:text-headplane-100',
+										)}
+										onClick={() => handleSort('version')}
+										type="button"
+									>
+										Version
+										{sortField === 'version' &&
+											(sortDirection === 'asc' ? (
+												<ChevronUp className="w-3 h-3" />
+											) : (
+												<ChevronDown className="w-3 h-3" />
+											))}
+									</button>
+								</th>
+							) : undefined}
+							<th
+								aria-sort={
+									sortField === 'lastSeen'
+										? sortDirection === 'asc'
+											? 'ascending'
+											: 'descending'
+										: 'none'
+								}
+								className="uppercase text-xs font-bold pb-2"
+							>
+								<button
+									aria-label="Sort by last seen"
+									className={cn(
+										'flex items-center gap-x-1 cursor-pointer',
+										'hover:text-headplane-900 dark:hover:text-headplane-100',
+									)}
+									onClick={() => handleSort('lastSeen')}
+									type="button"
+								>
+									Last Seen
+									{sortField === 'lastSeen' &&
+										(sortDirection === 'asc' ? (
+											<ChevronUp className="w-3 h-3" />
+										) : (
+											<ChevronDown className="w-3 h-3" />
+										))}
+								</button>
+							</th>
+						</tr>
+					</thead>
+					<tbody
+						className={cn(
+							'divide-y divide-headplane-100 dark:divide-headplane-800 align-top',
+							'border-t border-headplane-100 dark:border-headplane-800',
+						)}
+					>
+						{filteredAndSortedNodes.length === 0 ? (
+							<tr>
+								<td
+									className="py-8 text-center text-headplane-500"
+									colSpan={loaderData.agent !== undefined ? 5 : 4}
+								>
+									No machines found matching "{searchQuery}"
+								</td>
+							</tr>
+						) : (
+							filteredAndSortedNodes.map((node) => (
+								<MachineRow
+									existingTags={sortNodeTags(loaderData.nodes)}
+									isAgent={
+										loaderData.agent
+											? loaderData.agent === node.nodeKey
+											: undefined
+									}
+									isDisabled={
+										loaderData.writable
+											? false // If the user has write permissions, they can edit all machines
+											: node.user.providerId?.split('/').pop() !==
+												loaderData.subject
+									}
+									key={node.id}
+									magic={loaderData.magic}
+									node={node}
+									users={loaderData.users}
+								/>
+							))
+						)}
+					</tbody>
+				</table>
+			</div>
 		</>
 	);
 }

app/routes/settings/auth-keys/actions.ts

@@ -1,12 +1,8 @@
-import { ActionFunctionArgs, data } from 'react-router';
-import { LoadContext } from '~/server';
+import { data } from 'react-router';
 import { Capabilities } from '~/server/web/roles';
-import { PreAuthKey } from '~/types';
+import type { Route } from './+types/overview';
 
-export async function authKeysAction({
-	request,
-	context,
-}: ActionFunctionArgs<LoadContext>) {
+export async function authKeysAction({ request, context }: Route.ActionArgs) {
 	const session = await context.sessions.auth(request);
 	const check = await context.sessions.check(
 		request,
@@ -20,7 +16,7 @@ export async function authKeysAction({
 	}
 
 	const formData = await request.formData();
-	const apiKey = session.api_key;
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 	const action = formData.get('action_id')?.toString();
 	if (!action) {
 		throw data('Missing `action_id` in the form data.', {
@@ -29,90 +25,71 @@ export async function authKeysAction({
 	}
 
 	switch (action) {
-		case 'add_preauthkey':
-			return await addPreAuthKey(formData, apiKey, context);
-		case 'expire_preauthkey':
-			return await expirePreAuthKey(formData, apiKey, context);
+		case 'add_preauthkey': {
+			const user = formData.get('user_id')?.toString();
+			if (!user) {
+				return data('Missing `user_id` in the form data.', {
+					status: 400,
+				});
+			}
+
+			const expiry = formData.get('expiry')?.toString();
+			if (!expiry) {
+				return data('Missing `expiry` in the form data.', {
+					status: 400,
+				});
+			}
+
+			const reusable = formData.get('reusable')?.toString();
+			if (!reusable) {
+				return data('Missing `reusable` in the form data.', {
+					status: 400,
+				});
+			}
+
+			const ephemeral = formData.get('ephemeral')?.toString();
+			if (!ephemeral) {
+				return data('Missing `ephemeral` in the form data.', {
+					status: 400,
+				});
+			}
+
+			// Extract the first "word" from expiry which is the day number
+			// Calculate the date X days from now using the day number
+			const day = Number(expiry.toString().split(' ')[0]);
+			const date = new Date();
+			date.setDate(date.getDate() + day);
+			await api.createPreAuthKey(
+				user,
+				ephemeral === 'on',
+				reusable === 'on',
+				date,
+				[], // TODO
+			);
+
+			return data('Pre-auth key created');
+		}
+		case 'expire_preauthkey': {
+			const key = formData.get('key')?.toString();
+			if (!key) {
+				return data('Missing `key` in the form data.', {
+					status: 400,
+				});
+			}
+
+			const user = formData.get('user_id')?.toString();
+			if (!user) {
+				return data('Missing `user_id` in the form data.', {
+					status: 400,
+				});
+			}
+
+			await api.expirePreAuthKey(user, key);
+			return data('Pre-auth key expired');
+		}
 		default:
 			return data('Invalid action', {
 				status: 400,
 			});
 	}
 }
-
-async function addPreAuthKey(
-	formData: FormData,
-	apiKey: string,
-	context: LoadContext,
-) {
-	const user = formData.get('user_id')?.toString();
-	if (!user) {
-		return data('Missing `user_id` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const expiry = formData.get('expiry')?.toString();
-	if (!expiry) {
-		return data('Missing `expiry` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const reusable = formData.get('reusable')?.toString();
-	if (!reusable) {
-		return data('Missing `reusable` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const ephemeral = formData.get('ephemeral')?.toString();
-	if (!ephemeral) {
-		return data('Missing `ephemeral` in the form data.', {
-			status: 400,
-		});
-	}
-
-	// Extract the first "word" from expiry which is the day number
-	// Calculate the date X days from now using the day number
-	const day = Number(expiry.toString().split(' ')[0]);
-	const date = new Date();
-	date.setDate(date.getDate() + day);
-
-	await context.client.post<{ preAuthKey: PreAuthKey }>(
-		'v1/preauthkey',
-		apiKey,
-		{
-			user,
-			ephemeral: ephemeral === 'on',
-			reusable: reusable === 'on',
-			expiration: date.toISOString(),
-			aclTags: [], // TODO
-		},
-	);
-
-	return data('Pre-auth key created');
-}
-
-async function expirePreAuthKey(
-	formData: FormData,
-	apiKey: string,
-	context: LoadContext,
-) {
-	const key = formData.get('key')?.toString();
-	if (!key) {
-		return data('Missing `key` in the form data.', {
-			status: 400,
-		});
-	}
-
-	const user = formData.get('user_id')?.toString();
-	if (!user) {
-		return data('Missing `user_id` in the form data.', {
-			status: 400,
-		});
-	}
-
-	await context.client.post('v1/preauthkey/expire', apiKey, { user, key });
-	return data('Pre-auth key expired');
-}

app/routes/settings/auth-keys/dialogs/add-auth-key.tsx

@@ -1,5 +1,4 @@
 import { Key, useState } from 'react';
-import { useFetcher } from 'react-router';
 import Dialog from '~/components/Dialog';
 import Link from '~/components/Link';
 import NumberInput from '~/components/NumberInput';
@@ -22,36 +21,38 @@ export default function AddAuthKey(data: AddAuthKeyProps) {
 			<Dialog.Button className="my-4">Create pre-auth key</Dialog.Button>
 			<Dialog.Panel>
 				<Dialog.Title>Generate auth key</Dialog.Title>
-				<input type="hidden" name="action_id" value="add_preauthkey" />
-				<input type="hidden" name="user_id" value={userId?.toString()} />
+				<input name="action_id" type="hidden" value="add_preauthkey" />
+				<input name="user_id" type="hidden" value={userId?.toString()} />
 				<Select
+					className="mb-2"
+					description="This is the user machines will belong to when they authenticate."
 					isRequired
 					label="User"
 					name="user"
-					placeholder="Select a user"
-					description="This is the user machines will belong to when they authenticate."
-					className="mb-2"
 					onSelectionChange={(value) => {
 						setUserId(value);
 					}}
+					placeholder="Select a user"
 				>
 					{data.users.map((user) => (
-					    <Select.Item key={user.id}>{user.name || user.displayName || user.email || user.id}</Select.Item>
+						<Select.Item key={user.id}>
+							{user.name || user.displayName || user.email || user.id}
+						</Select.Item>
 					))}
 				</Select>
 				<NumberInput
-					isRequired
-					name="expiry"
-					label="Key Expiration"
-					description="Set this key to expire after a certain number of days."
-					minValue={1}
-					maxValue={365_000} // 1000 years
 					defaultValue={90}
+					description="Set this key to expire after a certain number of days."
 					formatOptions={{
 						style: 'unit',
 						unit: 'day',
 						unitDisplay: 'short',
 					}}
+					isRequired
+					label="Key Expiration"
+					maxValue={365_000} // 1000 years
+					minValue={1}
+					name="expiry"
 				/>
 				<div className="flex justify-between items-center gap-2 mt-6">
 					<div>
@@ -61,15 +62,15 @@ export default function AddAuthKey(data: AddAuthKeyProps) {
 						</Dialog.Text>
 					</div>
 					<Switch
+						defaultSelected={reusable}
 						label="Reusable"
 						name="reusable"
-						defaultSelected={reusable}
 						onChange={() => {
 							setReusable(!reusable);
 						}}
 					/>
 				</div>
-				<input type="hidden" name="reusable" value={reusable.toString()} />
+				<input name="reusable" type="hidden" value={reusable.toString()} />
 				<div className="flex justify-between items-center gap-2 mt-6">
 					<div>
 						<Dialog.Text className="font-semibold">Ephemeral</Dialog.Text>
@@ -77,23 +78,23 @@ export default function AddAuthKey(data: AddAuthKeyProps) {
 							Devices authenticated with this key will be automatically removed
 							once they go offline.{' '}
 							<Link
-								to="https://tailscale.com/kb/1111/ephemeral-nodes"
 								name="Tailscale Ephemeral Nodes Documentation"
+								to="https://tailscale.com/kb/1111/ephemeral-nodes"
 							>
 								Learn more
 							</Link>
 						</Dialog.Text>
 					</div>
 					<Switch
+						defaultSelected={ephemeral}
 						label="Ephemeral"
 						name="ephemeral"
-						defaultSelected={ephemeral}
 						onChange={() => {
 							setEphemeral(!ephemeral);
 						}}
 					/>
 				</div>
-				<input type="hidden" name="ephemeral" value={ephemeral.toString()} />
+				<input name="ephemeral" type="hidden" value={ephemeral.toString()} />
 			</Dialog.Panel>
 		</Dialog>
 	);

app/routes/settings/auth-keys/dialogs/expire-auth-key.tsx

@@ -12,9 +12,9 @@ export default function ExpireAuthKey({ authKey, user }: ExpireAuthKeyProps) {
 			<Dialog.Button variant="heavy">Expire Key</Dialog.Button>
 			<Dialog.Panel variant="destructive">
 				<Dialog.Title>Expire auth key?</Dialog.Title>
-				<input type="hidden" name="action_id" value="expire_preauthkey" />
-				<input type="hidden" name="user_id" value={user.id} />
-				<input type="hidden" name="key" value={authKey.key} />
+				<input name="action_id" type="hidden" value="expire_preauthkey" />
+				<input name="user_id" type="hidden" value={user.id} />
+				<input name="key" type="hidden" value={authKey.key} />
 				<Dialog.Text>
 					Expiring this authentication key will immediately prevent it from
 					being used to authenticate new devices. This action cannot be undone.

app/routes/settings/auth-keys/overview.tsx

@@ -1,41 +1,29 @@
 import { FileKey2 } from 'lucide-react';
 import { useMemo, useState } from 'react';
-import type { ActionFunctionArgs, LoaderFunctionArgs } from 'react-router';
-import { Link as RemixLink, useLoaderData } from 'react-router';
+import { Link as RemixLink } from 'react-router';
 import Code from '~/components/Code';
 import Link from '~/components/Link';
 import Notice from '~/components/Notice';
 import Select from '~/components/Select';
 import TableList from '~/components/TableList';
-import type { LoadContext } from '~/server';
 import { Capabilities } from '~/server/web/roles';
-import type { PreAuthKey, User } from '~/types';
 import log from '~/utils/log';
+import type { Route } from './+types/overview';
 import { authKeysAction } from './actions';
 import AuthKeyRow from './auth-key-row';
 import AddAuthKey from './dialogs/add-auth-key';
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
-	const { users } = await context.client.get<{ users: User[] }>(
-		'v1/user',
-		session.api_key,
-	);
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 
+	const users = await api.getUsers();
 	const preAuthKeys = await Promise.all(
 		users
 			.filter((user) => user.name?.length > 0) // Filter out any invalid users
 			.map(async (user) => {
-				const qp = new URLSearchParams();
-				qp.set('user', user.id);
-
 				try {
-					const { preAuthKeys } = await context.client.get<{
-						preAuthKeys: PreAuthKey[];
-					}>(`v1/preauthkey?${qp.toString()}`, session.api_key);
+					const preAuthKeys = await api.getPreAuthKeys(user.id);
 					return {
 						success: true,
 						user,
@@ -47,7 +35,7 @@ export async function loader({
 						success: false,
 						user,
 						error,
-						preAuthKeys: [] as PreAuthKey[],
+						preAuthKeys: [],
 					};
 				}
 			}),
@@ -79,13 +67,12 @@ export async function loader({
 	};
 }
 
-export async function action(request: ActionFunctionArgs<LoadContext>) {
-	return authKeysAction(request);
-}
+export const action = authKeysAction;
 
 type Status = 'all' | 'active' | 'expired' | 'reusable' | 'ephemeral';
-export default function Page() {
-	const { keys, missing, users, url, access } = useLoaderData<typeof loader>();
+export default function Page({
+	loaderData: { keys, missing, users, url, access },
+}: Route.ComponentProps) {
 	const [selectedUser, setSelectedUser] = useState('__headplane_all');
 	const [status, setStatus] = useState<Status>('active');
 	const isDisabled =
@@ -198,7 +185,9 @@ export default function Page() {
 					{[
 						<Select.Item key="__headplane_all">All</Select.Item>,
 						...keys.map(({ user }) => (
-							<Select.Item key={user.id}>{user.name || user.displayName || user.email || user.id}</Select.Item>
+							<Select.Item key={user.id}>
+								{user.name || user.displayName || user.email || user.id}
+							</Select.Item>
 						)),
 					]}
 				</Select>

app/routes/settings/overview.tsx

@@ -1,25 +1,21 @@
 import { ArrowRight } from 'lucide-react';
-import {
-	LoaderFunctionArgs,
-	Link as RemixLink,
-	useLoaderData,
-} from 'react-router';
+import { Link as RemixLink } from 'react-router';
 import Link from '~/components/Link';
-import { LoadContext } from '~/server';
+import type { Route } from './+types/overview';
 
-export async function loader({ context }: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ context }: Route.LoaderArgs) {
 	return {
 		config: context.hs.writable(),
-		oidc: context.oidc,
+		isOidcEnabled: context.oidcConnector?.isValid ?? false,
 	};
 }
 
-export default function Page() {
-	const { config, oidc } = useLoaderData<typeof loader>();
-
+export default function Page({
+	loaderData: { config, isOidcEnabled },
+}: Route.ComponentProps) {
 	return (
 		<div className="flex flex-col gap-8 max-w-(--breakpoint-lg)">
-			<div className="flex flex-col w-2/3">
+			<div className="flex flex-col w-full sm:w-2/3">
 				<h1 className="text-2xl font-medium mb-4">Settings</h1>
 				<p>
 					The settings page is still under construction. As I'm able to add more
@@ -27,7 +23,7 @@ export default function Page() {
 					free to open an issue on the GitHub repository.
 				</p>
 			</div>
-			<div className="flex flex-col w-2/3">
+			<div className="flex flex-col w-full sm:w-2/3">
 				<h1 className="text-2xl font-medium mb-4">Pre-Auth Keys</h1>
 				<p>
 					Headscale fully supports pre-authentication keys in order to easily
@@ -47,9 +43,9 @@ export default function Page() {
 					<ArrowRight className="w-5 h-5 ml-2" />
 				</div>
 			</RemixLink>
-			{config && oidc ? (
+			{config && isOidcEnabled ? (
 				<>
-					<div className="flex flex-col w-2/3">
+					<div className="flex flex-col w-full sm:w-2/3">
 						<h1 className="text-2xl font-medium mb-4">
 							Authentication Restrictions
 						</h1>

app/routes/settings/restrictions/actions.ts

@@ -1,11 +1,11 @@
-import { ActionFunctionArgs, data } from 'react-router';
-import { LoadContext } from '~/server';
+import { data } from 'react-router';
 import { Capabilities } from '~/server/web/roles';
+import type { Route } from './+types/overview';
 
 export async function restrictionAction({
 	request,
 	context,
-}: ActionFunctionArgs<LoadContext>) {
+}: Route.ActionArgs) {
 	const check = await context.sessions.check(
 		request,
 		Capabilities.configure_iam,
@@ -31,29 +31,162 @@ export async function restrictionAction({
 		});
 	}
 
+	// We only need healthchecks which don't rely on an API key
+	const api = context.hsApi.getRuntimeClient('fake-api-key');
 	switch (action) {
 		case 'add_domain': {
-			return addDomain(formData, context);
+			const domain = formData.get('domain')?.toString()?.trim();
+			if (!domain) {
+				throw data('No domain provided.', {
+					status: 400,
+				});
+			}
+
+			const domains = [
+				...new Set([...(context.hs.c?.oidc?.allowed_domains ?? []), domain]),
+			];
+
+			await context.hs.patch([
+				{
+					path: 'oidc.allowed_domains',
+					value: domains,
+				},
+			]);
+
+			context.integration?.onConfigChange(api);
+			return data('Domain added successfully.');
 		}
 
 		case 'remove_domain': {
-			return removeDomain(formData, context);
+			const domain = formData.get('domain')?.toString()?.trim();
+			if (!domain) {
+				throw data('No domain provided.', {
+					status: 400,
+				});
+			}
+
+			const storedDomains = context.hs.c?.oidc?.allowed_domains ?? [];
+			if (!storedDomains.includes(domain)) {
+				// Domain not found in the list
+				throw data(`Domain "${domain}" not found in allowed domains.`, {
+					status: 400,
+				});
+			}
+
+			// Filter out the domain to remove it from the list
+			const domains = storedDomains.filter((d: string) => d !== domain);
+			await context.hs.patch([
+				{
+					path: 'oidc.allowed_domains',
+					value: domains,
+				},
+			]);
+			context.integration?.onConfigChange(api);
+			return data('Domain removed successfully.');
 		}
 
 		case 'add_group': {
-			return addGroup(formData, context);
+			const group = formData.get('group')?.toString()?.trim();
+			if (!group) {
+				throw data('No group provided.', {
+					status: 400,
+				});
+			}
+
+			const groups = [
+				...new Set([...(context.hs.c?.oidc?.allowed_groups ?? []), group]),
+			];
+
+			await context.hs.patch([
+				{
+					path: 'oidc.allowed_groups',
+					value: groups,
+				},
+			]);
+
+			context.integration?.onConfigChange(api);
+			return data('Group added successfully.');
 		}
 
 		case 'remove_group': {
-			return removeGroup(formData, context);
+			const group = formData.get('group')?.toString()?.trim();
+			if (!group) {
+				throw data('No group provided.', {
+					status: 400,
+				});
+			}
+
+			const storedGroups = context.hs.c?.oidc?.allowed_groups ?? [];
+			if (!storedGroups.includes(group)) {
+				// Group not found in the list
+				throw data(`Group "${group}" not found in allowed groups.`, {
+					status: 400,
+				});
+			}
+
+			// Filter out the group to remove it from the list
+			const groups = storedGroups.filter((d: string) => d !== group);
+			await context.hs.patch([
+				{
+					path: 'oidc.allowed_groups',
+					value: groups,
+				},
+			]);
+
+			context.integration?.onConfigChange(api);
+			return data('Group removed successfully.');
 		}
 
 		case 'add_user': {
-			return addUser(formData, context);
+			const user = formData.get('user')?.toString()?.trim();
+			if (!user) {
+				throw data('No user provided.', {
+					status: 400,
+				});
+			}
+
+			const users = [
+				...new Set([...(context.hs.c?.oidc?.allowed_users ?? []), user]),
+			];
+
+			await context.hs.patch([
+				{
+					path: 'oidc.allowed_users',
+					value: users,
+				},
+			]);
+
+			context.integration?.onConfigChange(api);
+			return data('User added successfully.');
 		}
 
 		case 'remove_user': {
-			return removeUser(formData, context);
+			const user = formData.get('user')?.toString()?.trim();
+			if (!user) {
+				throw data('No user provided.', {
+					status: 400,
+				});
+			}
+
+			const storedUsers = context.hs.c?.oidc?.allowed_users ?? [];
+			if (!storedUsers.includes(user)) {
+				// User not found in the list
+				throw data(`User "${user}" not found in allowed users.`, {
+					status: 400,
+				});
+			}
+
+			// Filter out the user to remove it from the list
+			const users = storedUsers.filter((d: string) => d !== user);
+			await context.hs.patch([
+				{
+					path: 'oidc.allowed_users',
+					value: users,
+				},
+			]);
+
+			context.integration?.onConfigChange(api);
+			return data('User removed successfully.');
 		}
 
 		default: {
@@ -63,159 +196,3 @@ export async function restrictionAction({
 		}
 	}
 }
-
-async function addDomain(formData: FormData, context: LoadContext) {
-	const domain = formData.get('domain')?.toString()?.trim();
-	if (!domain) {
-		throw data('No domain provided.', {
-			status: 400,
-		});
-	}
-
-	const domains = [
-		...new Set([...(context.hs.c?.oidc?.allowed_domains ?? []), domain]),
-	];
-
-	await context.hs.patch([
-		{
-			path: 'oidc.allowed_domains',
-			value: domains,
-		},
-	]);
-
-	context.integration?.onConfigChange(context.client);
-	return data('Domain added successfully.');
-}
-
-async function removeDomain(formData: FormData, context: LoadContext) {
-	const domain = formData.get('domain')?.toString()?.trim();
-	if (!domain) {
-		throw data('No domain provided.', {
-			status: 400,
-		});
-	}
-
-	const storedDomains = context.hs.c?.oidc?.allowed_domains ?? [];
-	if (!storedDomains.includes(domain)) {
-		// Domain not found in the list
-		throw data(`Domain "${domain}" not found in allowed domains.`, {
-			status: 400,
-		});
-	}
-
-	// Filter out the domain to remove it from the list
-	const domains = storedDomains.filter((d: string) => d !== domain);
-	await context.hs.patch([
-		{
-			path: 'oidc.allowed_domains',
-			value: domains,
-		},
-	]);
-
-	context.integration?.onConfigChange(context.client);
-	return data('Domain removed successfully.');
-}
-
-async function addUser(formData: FormData, context: LoadContext) {
-	const user = formData.get('user')?.toString()?.trim();
-	if (!user) {
-		throw data('No user provided.', {
-			status: 400,
-		});
-	}
-
-	const users = [
-		...new Set([...(context.hs.c?.oidc?.allowed_users ?? []), user]),
-	];
-
-	await context.hs.patch([
-		{
-			path: 'oidc.allowed_users',
-			value: users,
-		},
-	]);
-
-	context.integration?.onConfigChange(context.client);
-	return data('User added successfully.');
-}
-
-async function removeUser(formData: FormData, context: LoadContext) {
-	const user = formData.get('user')?.toString()?.trim();
-	if (!user) {
-		throw data('No user provided.', {
-			status: 400,
-		});
-	}
-
-	const storedUsers = context.hs.c?.oidc?.allowed_users ?? [];
-	if (!storedUsers.includes(user)) {
-		// User not found in the list
-		throw data(`User "${user}" not found in allowed users.`, {
-			status: 400,
-		});
-	}
-
-	// Filter out the user to remove it from the list
-	const users = storedUsers.filter((d: string) => d !== user);
-	await context.hs.patch([
-		{
-			path: 'oidc.allowed_users',
-			value: users,
-		},
-	]);
-
-	context.integration?.onConfigChange(context.client);
-	return data('User removed successfully.');
-}
-
-async function addGroup(formData: FormData, context: LoadContext) {
-	const group = formData.get('group')?.toString()?.trim();
-	if (!group) {
-		throw data('No group provided.', {
-			status: 400,
-		});
-	}
-
-	const groups = [
-		...new Set([...(context.hs.c?.oidc?.allowed_groups ?? []), group]),
-	];
-
-	await context.hs.patch([
-		{
-			path: 'oidc.allowed_groups',
-			value: groups,
-		},
-	]);
-
-	context.integration?.onConfigChange(context.client);
-	return data('Group added successfully.');
-}
-
-async function removeGroup(formData: FormData, context: LoadContext) {
-	const group = formData.get('group')?.toString()?.trim();
-	if (!group) {
-		throw data('No group provided.', {
-			status: 400,
-		});
-	}
-
-	const storedGroups = context.hs.c?.oidc?.allowed_groups ?? [];
-	if (!storedGroups.includes(group)) {
-		// Group not found in the list
-		throw data(`Group "${group}" not found in allowed groups.`, {
-			status: 400,
-		});
-	}
-
-	// Filter out the group to remove it from the list
-	const groups = storedGroups.filter((d: string) => d !== group);
-	await context.hs.patch([
-		{
-			path: 'oidc.allowed_groups',
-			value: groups,
-		},
-	]);
-
-	context.integration?.onConfigChange(context.client);
-	return data('Group removed successfully.');
-}

app/routes/settings/restrictions/dialogs/add-domain.tsx

@@ -39,19 +39,19 @@ export default function AddDomain({ domains, isDisabled }: AddDomainProps) {
 					Add this domain to a list of allowed email domains that can
 					authenticate with Headscale via OIDC.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="add_domain" />
+				<input name="action_id" type="hidden" value="add_domain" />
 				<Input
-					isRequired
-					label="Domain"
 					description={
 						domain.trim().length > 0
 							? `Matches users with <user>@${domain.trim()}`
 							: 'Enter a domain to match users with their email addresses.'
 					}
-					placeholder="example.com"
+					isInvalid={domain.trim().length === 0 || isInvalid}
+					isRequired
+					label="Domain"
 					name="domain"
 					onChange={setDomain}
-					isInvalid={domain.trim().length === 0 || isInvalid}
+					placeholder="example.com"
 				/>
 				{isInvalid && (
 					<p className="text-red-500 text-sm mt-2">

app/routes/settings/restrictions/dialogs/add-group.tsx

@@ -30,15 +30,15 @@ export default function AddGroup({ groups, isDisabled }: AddGroupProps) {
 					Add this group to a list of allowed groups that can authenticate with
 					Headscale via OIDC.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="add_group" />
+				<input name="action_id" type="hidden" value="add_group" />
 				<Input
+					description="The group to allow for OIDC authentication."
+					isInvalid={group.trim().length === 0 || isInvalid}
 					isRequired
 					label="Group"
-					description="The group to allow for OIDC authentication."
-					placeholder="admin"
 					name="group"
 					onChange={setGroup}
-					isInvalid={group.trim().length === 0 || isInvalid}
+					placeholder="admin"
 				/>
 				{isInvalid && (
 					<p className="text-red-500 text-sm mt-2">

app/routes/settings/restrictions/dialogs/add-user.tsx

@@ -30,15 +30,15 @@ export default function AddUser({ users, isDisabled }: AddUserProps) {
 					Add this user to a list of allowed users that can authenticate with
 					Headscale via OIDC.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="add_user" />
+				<input name="action_id" type="hidden" value="add_user" />
 				<Input
+					description="The user to allow for OIDC authentication."
+					isInvalid={user.trim().length === 0 || isInvalid}
 					isRequired
 					label="User"
-					description="The user to allow for OIDC authentication."
-					placeholder="john_doe"
 					name="user"
 					onChange={setUser}
-					isInvalid={user.trim().length === 0 || isInvalid}
+					placeholder="john_doe"
 				/>
 				{isInvalid && (
 					<p className="text-red-500 text-sm mt-2">

app/routes/settings/restrictions/overview.tsx

@@ -1,24 +1,15 @@
-import {
-	ActionFunctionArgs,
-	LoaderFunctionArgs,
-	Link as RemixLink,
-	data,
-	useLoaderData,
-} from 'react-router';
+import { data, Link as RemixLink } from 'react-router';
 import Link from '~/components/Link';
 import Notice from '~/components/Notice';
-import { LoadContext } from '~/server';
 import { Capabilities } from '~/server/web/roles';
+import type { Route } from './+types/overview';
 import { restrictionAction } from './actions';
 import AddDomain from './dialogs/add-domain';
 import AddGroup from './dialogs/add-group';
 import AddUser from './dialogs/add-user';
 import RestrictionTable from './table';
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	const check = await context.sessions.check(request, Capabilities.read_users);
 	if (!check) {
 		throw data('You do not have permission to view IAM settings.', {
@@ -43,19 +34,18 @@ export async function loader({
 	};
 }
 
-export async function action(request: ActionFunctionArgs) {
-	return restrictionAction(request);
-}
+export const action = restrictionAction;
 
-export default function Page() {
-	const { access, writable, settings } = useLoaderData<typeof loader>();
+export default function Page({
+	loaderData: { access, writable, settings },
+}: Route.ComponentProps) {
 	const isDisabled = writable ? !access : true;
 
 	return (
 		<div className="flex flex-col gap-4 max-w-(--breakpoint-lg)">
-			<div className="flex flex-col w-2/3">
+			<div className="flex flex-col w-full sm:w-2/3">
 				<p className="mb-4 text-md">
-					<RemixLink to="/settings" className="font-medium">
+					<RemixLink className="font-medium" to="/settings">
 						Settings
 					</RemixLink>
 					<span className="mx-2">/</span> Authentication Restrictions
@@ -85,33 +75,33 @@ export default function Page() {
 					used to limit access to your Tailnet to only certain users or groups
 					and Headplane will also respect these settings when authenticating.{' '}
 					<Link
-						to="https://headscale.net/stable/ref/oidc/#basic-configuration"
 						name="Headscale OIDC documentation"
+						to="https://headscale.net/stable/ref/oidc/#basic-configuration"
 					>
 						Learn More
 					</Link>
 				</p>
 			</div>
 			<RestrictionTable
+				isDisabled={isDisabled}
 				type="domain"
 				values={settings.domains}
-				isDisabled={isDisabled}
 			>
 				<AddDomain domains={settings.domains} isDisabled={isDisabled} />
 			</RestrictionTable>
 			<RestrictionTable
+				isDisabled={isDisabled}
 				type="group"
 				values={settings.groups}
-				isDisabled={isDisabled}
 			>
 				<AddGroup groups={settings.groups} isDisabled={isDisabled} />
 			</RestrictionTable>
 			<RestrictionTable
+				isDisabled={isDisabled}
 				type="user"
 				values={settings.users}
-				isDisabled={isDisabled}
 			>
-				<AddUser users={settings.users} isDisabled={isDisabled} />
+				<AddUser isDisabled={isDisabled} users={settings.users} />
 			</RestrictionTable>
 		</div>
 	);

app/routes/settings/restrictions/table.tsx

@@ -19,7 +19,7 @@ export default function RestrictionTable({
 	isDisabled,
 }: RestrictionProps) {
 	return (
-		<div className="w-2/3">
+		<div className="w-full sm:w-2/3">
 			<h2 className="text-2xl font-medium mt-8">
 				Permitted {type.charAt(0).toUpperCase() + type.slice(1)}s
 			</h2>
@@ -40,18 +40,18 @@ export default function RestrictionTable({
 							)}
 							<Form method="POST">
 								<input
-									type="hidden"
 									name="action_id"
+									type="hidden"
 									value={`remove_${type}`}
 								/>
-								<input type="hidden" name={type} value={value} />
+								<input name={type} type="hidden" value={value} />
 								<Button
-									isDisabled={isDisabled}
-									type="submit"
 									className={cn(
 										'px-2 py-1 rounded-md',
 										'text-red-500 dark:text-red-400',
 									)}
+									isDisabled={isDisabled}
+									type="submit"
 								>
 									Remove
 								</Button>
@@ -61,7 +61,7 @@ export default function RestrictionTable({
 				) : (
 					<TableList.Item className="flex flex-col items-center gap-2.5 py-4 opacity-70">
 						{iconForType(type)}
-						<p className="font-semibold">
+						<p className="font-semibold text-center">
 							All {type}s are permitted to authenticate.
 						</p>
 					</TableList.Item>

app/routes/ssh/console.tsx

@@ -4,20 +4,11 @@ import { faker } from '@faker-js/faker';
 import { eq } from 'drizzle-orm';
 import { Loader2 } from 'lucide-react';
 import { useEffect, useState } from 'react';
-import {
-	ActionFunctionArgs,
-	data,
-	LinksFunction,
-	LoaderFunctionArgs,
-	ShouldRevalidateFunction,
-	useLoaderData,
-	useSubmit,
-} from 'react-router';
+import { data, type ShouldRevalidateFunction, useSubmit } from 'react-router';
 import { ExternalScriptsHandle } from 'remix-utils/external-scripts';
-import { LoadContext } from '~/server';
 import { EphemeralNodeInsert, ephemeralNodes } from '~/server/db/schema';
-import { Machine, PreAuthKey, User } from '~/types';
 import { useLiveData } from '~/utils/live-data';
+import type { Route } from './+types/console';
 import UserPrompt from './user-prompt';
 import XTerm from './xterm.client';
 
@@ -25,10 +16,7 @@ export const shouldRevalidate: ShouldRevalidateFunction = () => {
 	return false;
 };
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	const origin = new URL(request.url).origin;
 	const assets = ['/wasm_exec.js', '/hp_ssh.wasm'];
 	const missing: string[] = [];
@@ -53,10 +41,9 @@ export async function loader({
 	if (session.user.subject === 'unknown-non-oauth') {
 		throw data('Only OAuth users are allowed to use WebSSH', 403);
 	}
-	const { users } = await context.client.get<{ users: User[] }>(
-		'v1/user',
-		session.api_key,
-	);
+
+	const api = context.hsApi.getRuntimeClient(session.api_key);
+	const users = await api.getUsers();
 
 	// MARK: This assumes that a user has authenticated with Headscale first
 	// Since the only way to enforce permissions via ACLs is to generate a
@@ -77,15 +64,12 @@ export async function loader({
 		);
 	}
 
-	const { preAuthKey } = await context.client.post<{ preAuthKey: PreAuthKey }>(
-		'v1/preauthkey',
-		session.api_key,
-		{
-			user: lookup.id,
-			reusable: false,
-			ephemeral: true,
-			expiration: new Date(Date.now() + 60 * 1000).toISOString(), // 1 minute
-		},
+	const preAuthKey = await api.createPreAuthKey(
+		lookup.id,
+		true, // ephemeral
+		false, // reusable
+		new Date(Date.now() + 60 * 1000), // expiration: 1 minute
+		null, // aclTags
 	);
 
 	// TODO: Enable config to enforce generate_authkeys capability
@@ -130,13 +114,8 @@ export async function loader({
 	// 	);
 	// }
 
-	const { nodes } = await context.client.get<{ nodes: Machine[] }>(
-		'v1/node',
-		session.api_key,
-	);
-
-	// node.name is the hostname, given_name is the set name
-	const lookupNode = nodes.find((n) => n.name === hostname);
+	const nodes = await api.getNodes();
+	const lookupNode = nodes.find((n) => n.givenName === hostname);
 	if (!lookupNode) {
 		throw data(`Node with hostname ${hostname} not found`, 404);
 	}
@@ -182,11 +161,8 @@ function generateHostname(username: string) {
 	return `ssh-${adjective}-${noun}-${username}`;
 }
 
-export async function action({
-	request,
-	context,
-}: ActionFunctionArgs<LoadContext>) {
-	const _session = await context.sessions.auth(request);
+export async function action({ request, context }: Route.ActionArgs) {
+	await context.sessions.auth(request);
 	if (!context.agents?.agentID()) {
 		throw data(
 			'WebSSH is only available with the Headplane agent integration',
@@ -214,7 +190,7 @@ export async function action({
 		.where(eq(ephemeralNodes.auth_key, authKey));
 }
 
-export const links: LinksFunction = () => [
+export const links: Route.LinksFunction = () => [
 	{
 		rel: 'preload',
 		href: '/hp_ssh.wasm',
@@ -234,13 +210,14 @@ export const handle: ExternalScriptsHandle = {
 	],
 };
 
-export default function Page() {
+export default function Page({
+	loaderData: { ipnDetails, sshDetails },
+}: Route.ComponentProps) {
 	const submit = useSubmit();
 	const { pause } = useLiveData();
 
 	const [ipn, setIpn] = useState<TsWasmNet | null>(null);
 	const [nodeKey, setNodeKey] = useState<string | null>(null);
-	const { ipnDetails, sshDetails } = useLoaderData<typeof loader>();
 
 	useEffect(() => {
 		if (!ipnDetails) {

app/routes/users/components/manage-banner.tsx

@@ -1,17 +1,16 @@
 import { Building2, House, Key } from 'lucide-react';
 import Card from '~/components/Card';
 import Link from '~/components/Link';
-import type { HeadplaneConfig } from '~/server/config/schema';
 import CreateUser from '../dialogs/create-user';
 
 interface ManageBannerProps {
-	oidc?: NonNullable<HeadplaneConfig['oidc']>;
+	oidc?: { issuer: string };
 	isDisabled?: boolean;
 }
 
 export default function ManageBanner({ oidc, isDisabled }: ManageBannerProps) {
 	return (
-		<Card variant="flat" className="mb-8 w-full max-w-full p-0">
+		<Card className="mb-8 w-full max-w-full p-0" variant="flat">
 			<div className="flex flex-col md:flex-row">
 				<div className="w-full p-4 border-b md:border-b-0 border-headplane-100 dark:border-headplane-800">
 					{oidc ? (
@@ -26,14 +25,14 @@ export default function ManageBanner({ oidc, isDisabled }: ManageBannerProps) {
 						{oidc ? (
 							<>
 								Users are managed through your{' '}
-								<Link to={oidc.issuer} name="OIDC Provider">
+								<Link name="OIDC Provider" to={oidc.issuer}>
 									OpenID Connect provider
 								</Link>
 								{'. '}
 								Groups and user information do not automatically sync.{' '}
 								<Link
-									to="https://headscale.net/stable/ref/oidc"
 									name="Headscale OIDC Documentation"
+									to="https://headscale.net/stable/ref/oidc"
 								>
 									Learn more
 								</Link>
@@ -43,8 +42,8 @@ export default function ManageBanner({ oidc, isDisabled }: ManageBannerProps) {
 								Users are not managed externally. Using OpenID Connect can
 								create a better experience when using Headscale.{' '}
 								<Link
-									to="https://headscale.net/stable/ref/oidc"
 									name="Headscale OIDC Documentation"
+									to="https://headscale.net/stable/ref/oidc"
 								>
 									Learn more
 								</Link>
@@ -61,7 +60,7 @@ export default function ManageBanner({ oidc, isDisabled }: ManageBannerProps) {
 							: 'You can add, remove, and rename users here.'}
 					</p>
 					<div className="flex items-center gap-2 mt-4">
-						<CreateUser isOidc={oidc !== undefined} isDisabled={isDisabled} />
+						<CreateUser isDisabled={isDisabled} isOidc={oidc !== undefined} />
 					</div>
 				</div>
 			</div>

app/routes/users/components/menu.tsx

@@ -22,40 +22,40 @@ export default function UserMenu({ user }: MenuProps) {
 		<>
 			{modal === 'rename' && (
 				<Rename
-					user={user}
 					isOpen={modal === 'rename'}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
+					user={user}
 				/>
 			)}
 			{modal === 'delete' && (
 				<Delete
-					user={user}
 					isOpen={modal === 'delete'}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
+					user={user}
 				/>
 			)}
 			{modal === 'reassign' && (
 				<Reassign
-					user={user}
 					isOpen={modal === 'reassign'}
 					setIsOpen={(isOpen) => {
 						if (!isOpen) setModal(null);
 					}}
+					user={user}
 				/>
 			)}
 
 			<Menu disabledKeys={user.provider === 'oidc' ? ['rename'] : ['reassign']}>
 				<Menu.IconButton
-					label="Machine Options"
 					className={cn(
 						'py-0.5 w-10 bg-transparent border-transparent',
 						'border group-hover:border-headplane-200',
 						'dark:group-hover:border-headplane-700',
 					)}
+					label="Machine Options"
 				>
 					<Ellipsis className="h-5" />
 				</Menu.IconButton>

app/routes/users/components/user-row.tsx

@@ -18,22 +18,24 @@ export default function UserRow({ user, role }: UserRowProps) {
 
 	return (
 		<tr
-			key={user.id}
 			className="group hover:bg-headplane-50 dark:hover:bg-headplane-950"
+			key={user.id}
 		>
 			<td className="pl-0.5 py-2">
 				<div className="flex items-center">
 					{user.profilePicUrl ? (
 						<img
-							src={user.profilePicUrl}
 							alt={user.name || user.displayName}
 							className="w-10 h-10 rounded-full"
+							src={user.profilePicUrl}
 						/>
 					) : (
 						<CircleUser className="w-10 h-10" />
 					)}
 					<div className="ml-4">
-						<p className={cn('font-semibold leading-snug')}>{user.name || user.displayName}</p>
+						<p className={cn('font-semibold leading-snug')}>
+							{user.name || user.displayName}
+						</p>
 						<p className="text-sm opacity-50">{user.email}</p>
 					</div>
 				</div>
@@ -43,8 +45,8 @@ export default function UserRow({ user, role }: UserRowProps) {
 			</td>
 			<td className="pl-0.5 py-2">
 				<p
-					suppressHydrationWarning
 					className="text-sm text-headplane-600 dark:text-headplane-300"
+					suppressHydrationWarning
 				>
 					{new Date(user.createdAt).toLocaleDateString()}
 				</p>
@@ -56,7 +58,7 @@ export default function UserRow({ user, role }: UserRowProps) {
 						'text-headplane-600 dark:text-headplane-300',
 					)}
 				>
-					<StatusCircle isOnline={isOnline} className="w-4 h-4" />
+					<StatusCircle className="w-4 h-4" isOnline={isOnline} />
 					<p suppressHydrationWarning>
 						{isOnline ? 'Connected' : new Date(lastSeen).toLocaleString()}
 					</p>

app/routes/users/dialogs/create-user.tsx

@@ -24,15 +24,14 @@ export default function CreateUser({ isOidc, isDisabled }: CreateUserProps) {
 						</>
 					) : undefined}
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="create_user" />
+				<input name="action_id" type="hidden" value="create_user" />
 				<div className="flex flex-col gap-4">
 					<Input
 						isRequired
-						name="username"
-						type="text"
 						label="Username"
+						name="username"
 						placeholder="my-new-user"
-						validationBehavior="native"
+						type="text"
 						validate={(value) => {
 							if (value.trim().length === 0) {
 								return 'Username is required';
@@ -44,19 +43,20 @@ export default function CreateUser({ isOidc, isDisabled }: CreateUserProps) {
 
 							return true;
 						}}
-					/>
-					<Input
-						name="display_name"
-						type="text"
-						label="Display Name"
-						placeholder="John Doe"
 						validationBehavior="native"
 					/>
 					<Input
-						name="email"
-						type="email"
+						label="Display Name"
+						name="display_name"
+						placeholder="John Doe"
+						type="text"
+						validationBehavior="native"
+					/>
+					<Input
 						label="Email"
+						name="email"
 						placeholder="name@example.com"
+						type="email"
 						validationBehavior="native"
 					/>
 				</div>

app/routes/users/dialogs/delete-user.tsx

@@ -32,8 +32,8 @@ export default function DeleteUser({ user, isOpen, setIsOpen }: DeleteProps) {
 						)}
 					</Dialog.Text>
 				)}
-				<input type="hidden" name="action_id" value="delete_user" />
-				<input type="hidden" name="user_id" value={user.id} />
+				<input name="action_id" type="hidden" value="delete_user" />
+				<input name="user_id" type="hidden" value={user.id} />
 			</Dialog.Panel>
 		</Dialog>
 	);

app/routes/users/dialogs/reassign-user.tsx

@@ -21,14 +21,16 @@ export default function ReassignUser({
 			<Dialog.Panel
 				variant={user.headplaneRole === 'owner' ? 'unactionable' : 'normal'}
 			>
-				<Dialog.Title>Change role for {user.name || user.displayName}?</Dialog.Title>
+				<Dialog.Title>
+					Change role for {user.name || user.displayName}?
+				</Dialog.Title>
 				<Dialog.Text className="mb-6">
 					Most roles are carried straight from Tailscale. However, keep in mind
 					that I have not fully implemented permissions yet and some things may
 					be accessible to everyone. The only fully completed role is Member.{' '}
 					<Link
-						to="https://tailscale.com/kb/1138/user-roles"
 						name="Tailscale User Roles documentation"
+						to="https://tailscale.com/kb/1138/user-roles"
 					>
 						Learn More
 					</Link>
@@ -37,21 +39,21 @@ export default function ReassignUser({
 					<Notice>The Tailnet owner cannot be reassigned.</Notice>
 				) : (
 					<>
-						<input type="hidden" name="action_id" value="reassign_user" />
-						<input type="hidden" name="user_id" value={user.id} />
+						<input name="action_id" type="hidden" value="reassign_user" />
+						<input name="user_id" type="hidden" value={user.id} />
 						<RadioGroup
-							isRequired
-							name="new_role"
-							label="Role"
 							className="gap-4"
 							defaultValue={user.headplaneRole}
+							isRequired
+							label="Role"
+							name="new_role"
 						>
 							{Object.keys(Roles)
 								.filter((role) => role !== 'owner')
 								.map((role) => {
 									const { name, desc } = mapRoleToName(role);
 									return (
-										<RadioGroup.Radio key={role} value={role} label={name}>
+										<RadioGroup.Radio key={role} label={name} value={role}>
 											<div className="block">
 												<p className="font-bold">{name}</p>
 												<p className="opacity-70">{desc}</p>

app/routes/users/dialogs/rename-user.tsx

@@ -15,18 +15,18 @@ export default function RenameUser({ user, isOpen, setIsOpen }: RenameProps) {
 			<Dialog.Panel>
 				<Dialog.Title>Rename {user.name || user.displayName}?</Dialog.Title>
 				<Dialog.Text className="mb-6">
-					Enter a new username for {user.name || user.displayName}. Changing a username will not
-					update any ACL policies that may refer to this user by their old
-					username.
+					Enter a new username for {user.name || user.displayName}. Changing a
+					username will not update any ACL policies that may refer to this user
+					by their old username.
 				</Dialog.Text>
-				<input type="hidden" name="action_id" value="rename_user" />
-				<input type="hidden" name="user_id" value={user.id} />
+				<input name="action_id" type="hidden" value="rename_user" />
+				<input name="user_id" type="hidden" value={user.id} />
 				<Input
-					isRequired
-					name="new_name"
-					label="Username"
-					placeholder="my-new-name"
 					defaultValue={user.name}
+					isRequired
+					label="Username"
+					name="new_name"
+					placeholder="my-new-name"
 				/>
 			</Dialog.Panel>
 		</Dialog>

app/routes/users/onboarding-skip.tsx

@@ -1,12 +1,9 @@
 import { eq } from 'drizzle-orm';
-import { LoaderFunctionArgs, redirect } from 'react-router';
-import { LoadContext } from '~/server';
+import { redirect } from 'react-router';
 import { users } from '~/server/db/schema';
+import type { Route } from './+types/onboarding-skip';
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	try {
 		const { user } = await context.sessions.auth(request);
 		await context.db

app/routes/users/onboarding.tsx

@@ -1,23 +1,20 @@
 import { Icon } from '@iconify/react';
 import { ArrowRight } from 'lucide-react';
 import { useEffect } from 'react';
-import { LoaderFunctionArgs, NavLink, useLoaderData } from 'react-router';
+import { NavLink } from 'react-router';
 import Button from '~/components/Button';
 import Card from '~/components/Card';
 import Link from '~/components/Link';
 import Options from '~/components/Options';
 import StatusCircle from '~/components/StatusCircle';
-import { LoadContext } from '~/server';
 import { Machine } from '~/types';
 import cn from '~/utils/cn';
 import { useLiveData } from '~/utils/live-data';
 import log from '~/utils/log';
 import toast from '~/utils/toast';
+import type { Route } from './+types/onboarding';
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
 
 	// Try to determine the OS split between Linux, Windows, macOS, iOS, and Android
@@ -48,13 +45,10 @@ export async function loader({
 			break;
 	}
 
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 	let firstMachine: Machine | undefined;
 	try {
-		const { nodes } = await context.client.get<{ nodes: Machine[] }>(
-			'v1/node',
-			session.api_key,
-		);
-
+		const nodes = await api.getNodes();
 		const node = nodes.find((n) => {
 			if (n.user.provider !== 'oidc') {
 				return false;
@@ -87,8 +81,9 @@ export async function loader({
 	};
 }
 
-export default function Page() {
-	const { user, osValue, firstMachine } = useLoaderData<typeof loader>();
+export default function Page({
+	loaderData: { user, osValue, firstMachine },
+}: Route.ComponentProps) {
 	const { pause, resume } = useLiveData();
 	useEffect(() => {
 		if (firstMachine) {

app/routes/users/overview.tsx

@@ -1,10 +1,9 @@
+import { createHash } from 'node:crypto';
 import { useEffect, useState } from 'react';
-import type { ActionFunctionArgs, LoaderFunctionArgs } from 'react-router';
-import { useLoaderData } from 'react-router';
-import type { LoadContext } from '~/server';
 import { Capabilities } from '~/server/web/roles';
-import { Machine, User } from '~/types';
+import type { Machine, User } from '~/types';
 import cn from '~/utils/cn';
+import type { Route } from './+types/overview';
 import ManageBanner from './components/manage-banner';
 import UserRow from './components/user-row';
 import { userAction } from './user-actions';
@@ -13,10 +12,7 @@ interface UserMachine extends User {
 	machines: Machine[];
 }
 
-export async function loader({
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
+export async function loader({ request, context }: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
 	const check = await context.sessions.check(request, Capabilities.read_users);
 	if (!check) {
@@ -31,14 +27,24 @@ export async function loader({
 		Capabilities.write_users,
 	);
 
-	const [machines, apiUsers] = await Promise.all([
-		context.client.get<{ nodes: Machine[] }>('v1/node', session.api_key),
-		context.client.get<{ users: User[] }>('v1/user', session.api_key),
-	]);
+	const api = context.hsApi.getRuntimeClient(session.api_key);
+	const [nodes, apiUsers] = await Promise.all([api.getNodes(), api.getUsers()]);
 
-	const users = apiUsers.users.map((user) => ({
+	const users = apiUsers.map((user) => ({
 		...user,
-		machines: machines.nodes.filter((machine) => machine.user.id === user.id),
+		machines: nodes.filter((node) => node.user.id === user.id),
+		profilePicUrl:
+			context.config.oidc?.profile_picture_source === 'gravatar'
+				? (() => {
+						if (!user.email) {
+							return undefined;
+						}
+
+						const emailHash = user.email.trim().toLowerCase();
+						const hash = createHash('sha256').update(emailHash).digest('hex');
+						return `https://www.gravatar.com/avatar/${hash}?s=200&d=identicon&r=x`;
+					})()
+				: user.profilePicUrl,
 	}));
 
 	const roles = await Promise.all(
@@ -77,28 +83,29 @@ export async function loader({
 
 	return {
 		writable: writablePermission, // whether the user can write to the API
-		oidc: context.config.oidc,
+		oidc: context.config.oidc
+			? {
+					issuer: context.config.oidc.issuer,
+				}
+			: undefined,
 		roles,
 		magic,
 		users,
 	};
 }
 
-export async function action(data: ActionFunctionArgs) {
-	return userAction(data);
-}
+export const action = userAction;
 
-export default function Page() {
-	const data = useLoaderData<typeof loader>();
-	const [users, setUsers] = useState<UserMachine[]>(data.users);
+export default function Page({ loaderData }: Route.ComponentProps) {
+	const [users, setUsers] = useState<UserMachine[]>(loaderData.users);
 
 	// This useEffect is entirely for the purpose of updating the users when the
 	// drag and drop changes the machines between users. It's pretty hacky, but
 	// the idea is to treat data.users as the source of truth and update the
 	// local state when it changes.
 	useEffect(() => {
-		setUsers(data.users);
-	}, [data.users]);
+		setUsers(loaderData.users);
+	}, [loaderData.users]);
 
 	return (
 		<>
@@ -106,33 +113,35 @@ export default function Page() {
 			<p className="mb-8 text-md">
 				Manage the users in your network and their permissions.
 			</p>
-			<ManageBanner isDisabled={!data.writable} oidc={data.oidc} />
-			<table className="table-auto w-full rounded-lg">
-				<thead className="text-headplane-600 dark:text-headplane-300">
-					<tr className="text-left px-0.5">
-						<th className="uppercase text-xs font-bold pb-2">User</th>
-						<th className="uppercase text-xs font-bold pb-2">Role</th>
-						<th className="uppercase text-xs font-bold pb-2">Created At</th>
-						<th className="uppercase text-xs font-bold pb-2">Last Seen</th>
-					</tr>
-				</thead>
-				<tbody
-					className={cn(
-						'divide-y divide-headplane-100 dark:divide-headplane-800 align-top',
-						'border-t border-headplane-100 dark:border-headplane-800',
-					)}
-				>
-					{users
-						.sort((a, b) => a.name.localeCompare(b.name))
-						.map((user) => (
-							<UserRow
-								key={user.id}
-								role={data.roles[users.indexOf(user)]}
-								user={user}
-							/>
-						))}
-				</tbody>
-			</table>
+			<ManageBanner isDisabled={!loaderData.writable} oidc={loaderData.oidc} />
+			<div className="overflow-x-auto">
+				<table className="table-auto w-full rounded-lg min-w-[640px]">
+					<thead className="text-headplane-600 dark:text-headplane-300">
+						<tr className="text-left px-0.5">
+							<th className="uppercase text-xs font-bold pb-2">User</th>
+							<th className="uppercase text-xs font-bold pb-2">Role</th>
+							<th className="uppercase text-xs font-bold pb-2">Created At</th>
+							<th className="uppercase text-xs font-bold pb-2">Last Seen</th>
+						</tr>
+					</thead>
+					<tbody
+						className={cn(
+							'divide-y divide-headplane-100 dark:divide-headplane-800 align-top',
+							'border-t border-headplane-100 dark:border-headplane-800',
+						)}
+					>
+						{users
+							.sort((a, b) => a.name.localeCompare(b.name))
+							.map((user) => (
+								<UserRow
+									key={user.id}
+									role={loaderData.roles[users.indexOf(user)]}
+									user={user}
+								/>
+							))}
+					</tbody>
+				</table>
+			</div>
 		</>
 	);
 }

app/routes/users/user-actions.ts

@@ -1,140 +1,115 @@
-import { ActionFunctionArgs, data } from 'react-router';
-import type { LoadContext } from '~/server';
+import { data } from 'react-router';
 import { Capabilities, Roles } from '~/server/web/roles';
-import { User } from '~/types';
-import { data400, data403 } from '~/utils/res';
+import type { Route } from './+types/overview';
 
-export async function userAction({
-	request,
-	context,
-}: ActionFunctionArgs<LoadContext>) {
+export async function userAction({ request, context }: Route.ActionArgs) {
 	const session = await context.sessions.auth(request);
 	const check = await context.sessions.check(request, Capabilities.write_users);
 	if (!check) {
-		throw data403('You do not have permission to update users');
+		throw data('You do not have permission to update users', {
+			status: 403,
+		});
 	}
 
-	const apiKey = session.api_key;
 	const formData = await request.formData();
 	const action = formData.get('action_id')?.toString();
 	if (!action) {
-		throw data400('Missing `action_id` in the form data.');
+		throw data('Missing `action_id` in the form data.', {
+			status: 404,
+		});
 	}
 
+	const api = context.hsApi.getRuntimeClient(session.api_key);
 	switch (action) {
-		case 'create_user':
-			return createUser(formData, apiKey, context);
-		case 'delete_user':
-			return deleteUser(formData, apiKey, context);
-		case 'rename_user':
-			return renameUser(formData, apiKey, context);
-		case 'reassign_user':
-			return reassignUser(formData, apiKey, context);
+		case 'create_user': {
+			const name = formData.get('username')?.toString();
+			const displayName = formData.get('display_name')?.toString();
+			const email = formData.get('email')?.toString();
+
+			if (!name) {
+				throw data('Missing `username` in the form data.', {
+					status: 400,
+				});
+			}
+
+			await api.createUser(name, email, displayName);
+			return { message: 'User created successfully' };
+		}
+		case 'delete_user': {
+			const userId = formData.get('user_id')?.toString();
+			if (!userId) {
+				throw data('Missing `user_id` in the form data.', {
+					status: 400,
+				});
+			}
+
+			await api.deleteUser(userId);
+			return { message: 'User deleted successfully' };
+		}
+		case 'rename_user': {
+			const userId = formData.get('user_id')?.toString();
+			const newName = formData.get('new_name')?.toString();
+			if (!userId || !newName) {
+				return data({ success: false }, 400);
+			}
+
+			const users = await api.getUsers(userId);
+			const user = users.find((user) => user.id === userId);
+			if (!user) {
+				throw data(`No user found with id: ${userId}`, { status: 400 });
+			}
+
+			if (user.provider === 'oidc') {
+				// OIDC users cannot be renamed via this endpoint, return an error
+				throw data('Users managed by OIDC cannot be renamed', {
+					status: 403,
+				});
+			}
+
+			await api.renameUser(userId, newName);
+			return { message: 'User renamed successfully' };
+		}
+		case 'reassign_user': {
+			const userId = formData.get('user_id')?.toString();
+			const newRole = formData.get('new_role')?.toString();
+			if (!userId || !newRole) {
+				throw data('Missing `user_id` or `new_role` in the form data.', {
+					status: 400,
+				});
+			}
+
+			const users = await api.getUsers(userId);
+			const user = users.find((user) => user.id === userId);
+			if (!user?.providerId) {
+				throw data('Specified user is not an OIDC user', {
+					status: 400,
+				});
+			}
+
+			// For some reason, headscale makes providerID a url where the
+			// last component is the subject, so we need to strip that out
+			const subject = user.providerId?.split('/').pop();
+			if (!subject) {
+				throw data(
+					'Malformed `providerId` for the specified user. Cannot find subject.',
+					{ status: 400 },
+				);
+			}
+
+			const result = await context.sessions.reassignSubject(
+				subject,
+				newRole as keyof typeof Roles,
+			);
+
+			if (!result) {
+				throw data('Failed to reassign user role.', { status: 500 });
+			}
+
+			return { message: 'User reassigned successfully' };
+		}
 		default:
-			throw data400('Invalid `action_id` provided.');
+			throw data('Invalid `action_id` provided.', {
+				status: 400,
+			});
 	}
 }
-
-async function createUser(
-	formData: FormData,
-	apiKey: string,
-	context: LoadContext,
-) {
-	const name = formData.get('username')?.toString();
-	const displayName = formData.get('display_name')?.toString();
-	const email = formData.get('email')?.toString();
-
-	if (!name) {
-		throw data400('Missing `username` in the form data.');
-	}
-
-	await context.client.post('v1/user', apiKey, {
-		name,
-		displayName,
-		email,
-	});
-}
-
-async function deleteUser(
-	formData: FormData,
-	apiKey: string,
-	context: LoadContext,
-) {
-	const userId = formData.get('user_id')?.toString();
-	if (!userId) {
-		throw data400('Missing `user_id` in the form data.');
-	}
-
-	await context.client.delete(`v1/user/${userId}`, apiKey);
-}
-
-async function renameUser(
-	formData: FormData,
-	apiKey: string,
-	context: LoadContext,
-) {
-	const userId = formData.get('user_id')?.toString();
-	const newName = formData.get('new_name')?.toString();
-	if (!userId || !newName) {
-		return data({ success: false }, 400);
-	}
-
-	const { users } = await context.client.get<{ users: User[] }>(
-		'v1/user',
-		apiKey,
-	);
-
-	const user = users.find((user) => user.id === userId);
-	if (!user) {
-		throw data400(`No user found with id: ${userId}`);
-	}
-
-	if (user.provider === 'oidc') {
-		// OIDC users cannot be renamed via this endpoint, return an error
-		throw data403('Users managed by OIDC cannot be renamed');
-	}
-
-	await context.client.post(`v1/user/${userId}/rename/${newName}`, apiKey);
-}
-
-async function reassignUser(
-	formData: FormData,
-	apiKey: string,
-	context: LoadContext,
-) {
-	const userId = formData.get('user_id')?.toString();
-	const newRole = formData.get('new_role')?.toString();
-	if (!userId || !newRole) {
-		throw data400('Missing `user_id` or `new_role` in the form data.');
-	}
-
-	const { users } = await context.client.get<{ users: User[] }>(
-		'v1/user',
-		apiKey,
-	);
-
-	const user = users.find((user) => user.id === userId);
-	if (!user?.providerId) {
-		throw data400('Specified user is not an OIDC user');
-	}
-
-	// For some reason, headscale makes providerID a url where the
-	// last component is the subject, so we need to strip that out
-	const subject = user.providerId?.split('/').pop();
-	if (!subject) {
-		throw data400(
-			'Malformed `providerId` for the specified user. Cannot find subject.',
-		);
-	}
-
-	const result = await context.sessions.reassignSubject(
-		subject,
-		newRole as keyof typeof Roles,
-	);
-
-	if (!result) {
-		return data({ success: false }, 403);
-	}
-
-	return data({ success: true });
-}

app/routes/util/healthz.ts

@@ -1,8 +1,10 @@
-import { LoaderFunctionArgs } from 'react-router';
-import type { LoadContext } from '~/server';
+import type { Route } from './+types/healthz';
+
+export async function loader({ context }: Route.LoaderArgs) {
+	// Use a fake API key for healthcheck
+	const api = context.hsApi.getRuntimeClient('fake-api-key');
+	const healthy = await api.isHealthy();
 
-export async function loader({ context }: LoaderFunctionArgs<LoadContext>) {
-	const healthy = await context.client.healthcheck();
 	return new Response(JSON.stringify({ status: healthy ? 'OK' : 'ERROR' }), {
 		status: healthy ? 200 : 500,
 		headers: {

app/routes/util/info.ts

@@ -0,0 +1,59 @@
+import { versions } from 'node:process';
+import { data } from 'react-router';
+import type { Route } from './+types/info';
+
+export async function loader({ request, context }: Route.LoaderArgs) {
+	if (context.config.server.info_secret == null) {
+		throw data(
+			{
+				status: 'Forbidden',
+			},
+			403,
+		);
+	}
+
+	const bearer = request.headers.get('Authorization') ?? '';
+	if (!bearer.startsWith('Bearer ')) {
+		throw data(
+			{
+				status: 'Unauthorized',
+			},
+			401,
+		);
+	}
+
+	const token = bearer.slice('Bearer '.length).trim();
+	if (token !== context.config.server.info_secret) {
+		throw data(
+			{
+				status: 'Forbidden',
+			},
+			403,
+		);
+	}
+
+	// Use a fake API key for healthcheck
+	const api = context.hsApi.getRuntimeClient('fake-api-key');
+	const healthy = await api.isHealthy();
+
+	const body = {
+		status: healthy ? 'healthy' : 'unhealthy',
+		headplane_version: __VERSION__,
+		headscale_canonical_version: healthy ? context.hsApi.apiVersion : 'unknown',
+		internal_versions: {
+			node: versions.node,
+			v8: versions.v8,
+			uv: versions.uv,
+			zlib: versions.zlib,
+			openssl: versions.openssl,
+			libc: versions.libc,
+		},
+	};
+
+	return new Response(JSON.stringify(body), {
+		status: 200,
+		headers: {
+			'Content-Type': 'application/json',
+		},
+	});
+}

app/server/README.md

@@ -1,33 +0,0 @@
-# Headplane Server
-This code is responsible for all code that is necessary *before* any
-web server is started. It is the only part of the code that contains
-many side-effects (in this case, importing a module may run code).
-
-# Hierarchy
-```
-server
-├── index.ts: Loads everything and starts the web server.
-├── agent/
-│   ├── dispatcher.ts: Serializes commands for the agent control fd (stdin).
-│   ├── ssh.ts: Manages & multiplexes the active web SSH connections
-│   ├── env.ts: Checks the environment variables for custom overrides.
-├── config/
-│   ├── integration/
-│   │   ├── abstract.ts: Defines the abstract class for integrations.
-│   │   ├── docker.ts: Contains the Docker integration.
-│   │   ├── index.ts: Determines the correct integration to use (if any).
-│   │   ├── kubernetes.ts: Contains the Kubernetes integration.
-│   │   ├── proc.ts: Contains the Proc integration.
-│   ├── env.ts: Checks the environment variables for custom overrides.
-│   ├── loader.ts: Checks the configuration file and coalesces with ENV.
-│   ├── schema.ts: Defines the schema for the Headplane configuration.
-├── headscale/
-│   ├── api-client.ts: Creates the HTTP client that talks to the Headscale API.
-│   ├── api-error.ts: Contains the ResponseError definition.
-│   ├── config-loader.ts: Loads the Headscale configuration (if available).
-│   ├── config-schema.ts: Defines the schema for the Headscale configuration.
-├── web/
-│   ├── agent.ts: Handles setting up the agent WebSocket if needed.
-│   ├── oidc.ts: Loads and validates an OIDC configuration (if available).
-│   ├── roles.ts: Contains information about authentication permissions.
-│   ├── sessions.ts: Initializes the session store and methods to manage it.

app/server/config/config-schema.ts

@@ -0,0 +1,206 @@
+import { type } from 'arktype';
+import log from '~/utils/log';
+import DockerIntegration from './integration/docker';
+import KubernetesIntegration from './integration/kubernetes';
+import ProcIntegration from './integration/proc';
+import { deprecatedField } from './utils';
+
+export const pathSupportedKeys = [
+	'server.cookie_secret',
+	'oidc.client_secret',
+	'oidc.headscale_api_key',
+	'integration.agent.pre_authkey',
+] as const;
+
+const serverConfig = type({
+	host: 'string.ip = "0.0.0.0"',
+	port: 'number.integer = 3000',
+	base_url: 'string.url?',
+	data_path: 'string.lower = "/var/lib/headplane/"',
+	info_secret: 'string?',
+
+	cookie_secret: '(32 <= string <= 32)',
+	cookie_secure: 'boolean = true',
+	cookie_domain: 'string.lower?',
+	cookie_max_age: 'number.integer = 86400',
+});
+
+const partialServerConfig = type({
+	host: 'string.ip?',
+	port: 'number.integer?',
+	base_url: 'string.url?',
+	data_path: 'string.lower?',
+	info_secret: 'string?',
+
+	cookie_secret: '(32 <= string <= 32)?',
+	cookie_secure: 'boolean?',
+	cookie_domain: 'string.lower?',
+	cookie_max_age: 'number.integer?',
+});
+
+const headscaleConfig = type({
+	url: type('string.url').pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v)),
+	public_url: type('string.url')
+		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
+		.optional(),
+	config_path: 'string.lower?',
+	config_strict: 'boolean = true',
+	dns_records_path: 'string.lower?',
+	tls_cert_path: 'string.lower?',
+});
+
+const partialHeadscaleConfig = type({
+	url: type('string.url')
+		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
+		.optional(),
+	public_url: type('string.url')
+		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
+		.optional(),
+	config_path: 'string.lower?',
+	config_strict: 'boolean?',
+	dns_records_path: 'string.lower?',
+	tls_cert_path: 'string.lower?',
+});
+
+const oidcConfig = type({
+	issuer: 'string.url',
+	client_id: 'string',
+	client_secret: 'string',
+	headscale_api_key: 'string',
+	use_pkce: 'boolean = false',
+	redirect_uri: type('string.url')
+		.pipe((value, ctx) => {
+			log.warn(
+				'config',
+				'%s is deprecated and will be removed in 0.7.0',
+				ctx.propString,
+			);
+
+			const cleanedValue = new URL(value.trim());
+			if (cleanedValue.pathname.endsWith(`${__PREFIX__}/oidc/callback`)) {
+				cleanedValue.pathname = cleanedValue.pathname.replace(
+					`${__PREFIX__}/oidc/callback`,
+					'/',
+				);
+
+				log.warn(
+					'config',
+					'Please migrate to using `server.base_url` with a value of "%s"',
+					cleanedValue.toString(),
+				);
+			}
+
+			return cleanedValue.toString();
+		})
+		.optional(),
+	disable_api_key_login: 'boolean = false',
+	scope: 'string = "openid email profile"',
+	profile_picture_source: '"oidc" | "gravatar" = "oidc"',
+	extra_params: 'Record<string, string>?',
+
+	authorization_endpoint: 'string.url?',
+	token_endpoint: 'string.url?',
+	userinfo_endpoint: 'string.url?',
+	token_endpoint_auth_method:
+		'"client_secret_basic" | "client_secret_post" | "client_secret_jwt"?',
+
+	// Old/deprecated options
+	user_storage_file: 'string.lower = "/var/lib/headplane/users.json"',
+	strict_validation: type('unknown').narrow(deprecatedField()).optional(),
+});
+
+const partialOidcConfig = type({
+	issuer: 'string.url?',
+	client_id: 'string?',
+	client_secret: 'string?',
+	use_pkce: 'boolean?',
+	headscale_api_key: 'string?',
+	redirect_uri: 'string.url?',
+	disable_api_key_login: 'boolean?',
+	scope: 'string?',
+	extra_params: 'Record<string, string>?',
+	profile_picture_source: '"oidc" | "gravatar"?',
+
+	authorization_endpoint: 'string.url?',
+	token_endpoint: 'string.url?',
+	userinfo_endpoint: 'string.url?',
+	token_endpoint_auth_method:
+		'"client_secret_basic" | "client_secret_post" | "client_secret_jwt"?',
+
+	// Old/deprecated options
+	user_storage_file: 'string.lower?',
+	strict_validation: type('unknown').narrow(deprecatedField()).optional(),
+});
+
+const agentConfig = type({
+	enabled: 'boolean',
+	host_name: 'string = "headplane-agent"',
+	pre_authkey: 'string',
+	cache_ttl: 'number.integer = 180000',
+	cache_path: 'string = "/var/lib/headplane/agent_cache.json"',
+	executable_path: 'string = "/usr/libexec/headplane/agent"',
+	work_dir: 'string = "/var/lib/headplane/agent"',
+});
+
+const partialAgentConfig = type({
+	enabled: 'boolean?',
+	host_name: 'string?',
+	pre_authkey: 'string?',
+	cache_ttl: 'number.integer?',
+	cache_path: 'string?',
+	executable_path: 'string?',
+	work_dir: 'string?',
+});
+
+const integrationConfig = type({
+	docker: DockerIntegration.configSchema.full,
+	kubernetes: KubernetesIntegration.configSchema.full,
+	proc: ProcIntegration.configSchema.full,
+	agent: agentConfig.optional(),
+}).partial();
+
+export const partialIntegrationConfig = type({
+	docker: DockerIntegration.configSchema.partial,
+	kubernetes: KubernetesIntegration.configSchema.partial,
+	proc: ProcIntegration.configSchema.partial,
+	agent: partialAgentConfig.optional(),
+}).partial();
+
+export const headplaneConfig = type({
+	debug: 'boolean = false',
+	server: serverConfig,
+	headscale: headscaleConfig,
+	oidc: oidcConfig.optional(),
+	integration: integrationConfig.optional(),
+}).onDeepUndeclaredKey('delete');
+
+export const partialHeadplaneConfig = type({
+	debug: 'boolean?',
+	server: partialServerConfig.optional(),
+	headscale: partialHeadscaleConfig.optional(),
+	oidc: partialOidcConfig.optional(),
+	integration: partialIntegrationConfig.optional(),
+});
+
+export type HeadplaneConfig = typeof headplaneConfig.infer;
+export type PartialHeadplaneConfig = typeof partialHeadplaneConfig.infer;
+
+type DotNotationToObjects<
+	T extends string,
+	V,
+> = T extends `${infer K}.${infer Rest}`
+	? { [P in K]?: DotNotationToObjects<Rest, V> }
+	: { [P in `${T}_path`]?: V };
+
+type ObjectDeepMerge<T> = T extends object
+	? {
+			[K in keyof T]: T[K] extends object ? ObjectDeepMerge<T[K]> : T[K];
+		}
+	: T;
+
+type ConfigWithPathKeys = ObjectDeepMerge<
+	DotNotationToObjects<(typeof pathSupportedKeys)[number], string | undefined>
+>;
+
+export type PartialHeadplaneConfigWithPaths = PartialHeadplaneConfig &
+	ConfigWithPathKeys;

app/server/config/env.ts

@@ -1,76 +0,0 @@
-import { exit } from 'node:process';
-import { type } from 'arktype';
-import log from '~/utils/log';
-
-// Custom type for boolean environment variables, allowing for values like
-// 1, true, yes, and on to count as a truthy value.
-const booleanEnv = type('string | undefined').pipe((v) => {
-	return ['1', 'true', 'yes', 'on'].includes(v?.toLowerCase() ?? '');
-});
-
-export const envVariables = {
-	debugLog: 'HEADPLANE_DEBUG_LOG',
-	envOverrides: 'HEADPLANE_LOAD_ENV_OVERRIDES',
-	configPath: 'HEADPLANE_CONFIG_PATH',
-} as const;
-
-export function configureLogger(env: string | undefined) {
-	const result = booleanEnv(env);
-	if (result instanceof type.errors) {
-		log.error(
-			'config',
-			'HEADPLANE_DEBUG_LOG value is invalid: %s',
-			result.summary,
-		);
-		log.info('config', 'Using a default value: false');
-		log.debug = () => {}; // Disable debug logging if the value is invalid
-		log.debugEnabled = false;
-		return;
-	}
-
-	if (result === false) {
-		log.debug = () => {}; // Disable debug logging if the value is false
-		log.debugEnabled = false;
-		return;
-	}
-
-	log.debug('config', 'Debug logging has been enabled');
-	log.debug('config', 'It is recommended this be disabled in production');
-}
-
-export interface EnvOverrides {
-	loadEnv: boolean;
-	path: string;
-}
-
-export function configureConfig(overrides: {
-	loadEnv: string | undefined;
-	path: string | undefined;
-}): EnvOverrides {
-	const loadResult = booleanEnv(overrides.loadEnv);
-	if (loadResult instanceof type.errors) {
-		log.error(
-			'config',
-			'HEADPLANE_LOAD_ENV_OVERRIDES value is invalid: %s',
-			loadResult.summary,
-		);
-
-		exit(1);
-	}
-
-	const pathResult = type('string | undefined')(overrides.path);
-	if (pathResult instanceof type.errors) {
-		log.error(
-			'config',
-			'HEADPLANE_CONFIG_PATH value is invalid: %s',
-			pathResult.summary,
-		);
-
-		exit(1);
-	}
-
-	return {
-		loadEnv: loadResult,
-		path: pathResult ?? '/etc/headplane/config.yaml',
-	};
-}

app/server/config/error.ts

@@ -0,0 +1,74 @@
+interface ErrorCodes {
+	CONFLICTING_SECRET_PATH_FIELD: {
+		fieldName: string;
+	};
+
+	INVALID_REQUIRED_FIELDS: {
+		messages: string[];
+	};
+
+	MISSING_INTERPOLATION_VARIABLE: {
+		pathKey: string;
+		variableName: string;
+	};
+
+	MISSING_SECRET_FILE: {
+		pathKey: string;
+		filePath: string;
+	};
+}
+
+const translationsWithVars: {
+	[K in keyof ErrorCodes]: (vars: ErrorCodes[K]) => string;
+} = {
+	CONFLICTING_SECRET_PATH_FIELD: ({ fieldName }) =>
+		`Both "${fieldName}" and "${fieldName}_path" are set; please provide only one of these fields.`,
+	INVALID_REQUIRED_FIELDS: ({ messages }) =>
+		`The configuration is missing required fields or has invalid values:\n- ${messages.join('\n- ')}`,
+	MISSING_INTERPOLATION_VARIABLE: ({ pathKey, variableName }) =>
+		`Could not resolve environment variable "${variableName}" for configuration key "${pathKey}".`,
+
+	MISSING_SECRET_FILE: ({ pathKey, filePath }) =>
+		`The secret file specified in "${pathKey}" could not be accessed at path "${filePath}". Please ensure the file exists and is readable.`,
+} as const;
+
+/**
+ * Custom error class for configuration-related errors.
+ */
+export class ConfigError extends Error {
+	/**
+	 * The error code representing the type of configuration error.
+	 */
+	code: keyof ErrorCodes;
+
+	/**
+	 * Creates a new ConfigError instance.
+	 *
+	 * @param code The error code
+	 * @param vars The variables to interpolate into the error message
+	 */
+	constructor(code: keyof ErrorCodes, vars: unknown) {
+		super(
+			translationsWithVars[code](
+				vars as (typeof translationsWithVars)[typeof code] extends (
+					vars: infer U,
+				) => string
+					? U
+					: never,
+			),
+		);
+		this.code = code;
+		this.name = 'ConfigError';
+	}
+
+	/**
+	 * Factory method to create a ConfigError instance.
+	 *
+	 * @param code The error code
+	 * @param vars The variables to interpolate into the error message
+	 * @returns A new ConfigError instance
+	 */
+	static from<K extends keyof ErrorCodes>(code: K, vars: ErrorCodes[K]) {
+		return new ConfigError(code, vars);
+	}
+}

app/server/config/integration/abstract.ts

@@ -1,4 +1,4 @@
-import type { ApiClient } from '~/server/headscale/api-client';
+import type { RuntimeApiClient } from '~/server/headscale/api/endpoints';
 
 export abstract class Integration<T> {
 	protected context: NonNullable<T>;
@@ -11,6 +11,6 @@ export abstract class Integration<T> {
 	}
 
 	abstract isAvailable(): Promise<boolean> | boolean;
-	abstract onConfigChange(client: ApiClient): Promise<void> | void;
+	abstract onConfigChange(client: RuntimeApiClient): Promise<void> | void;
 	abstract get name(): string;
 }

app/server/config/integration/docker.ts

@@ -1,9 +1,9 @@
-import { constants, access } from 'node:fs/promises';
+import { access, constants } from 'node:fs/promises';
 import { setTimeout } from 'node:timers/promises';
+import { type } from 'arktype';
 import { Client } from 'undici';
-import { ApiClient } from '~/server/headscale/api-client';
+import type { RuntimeApiClient } from '~/server/headscale/api/endpoints';
 import log from '~/utils/log';
-import type { HeadplaneConfig } from '../schema';
 import { Integration } from './abstract';
 
 interface DockerContainer {
@@ -11,8 +11,25 @@ interface DockerContainer {
 	Names: string[];
 }
 
-type T = NonNullable<HeadplaneConfig['integration']>['docker'];
-export default class DockerIntegration extends Integration<T> {
+const configSchema = {
+	full: type({
+		enabled: 'boolean',
+		container_name: 'string?',
+		container_label: 'string = "me.tale.headplane.target=headscale"',
+		socket: 'string = "unix:///var/run/docker.sock"',
+	}),
+
+	partial: type({
+		enabled: 'boolean?',
+		container_name: 'string?',
+		container_label: 'string?',
+		socket: 'string?',
+	}).partial(),
+};
+
+export default class DockerIntegration extends Integration<
+	typeof configSchema.full.infer
+> {
 	private maxAttempts = 10;
 	private client: Client | undefined;
 	private containerId: string | undefined;
@@ -21,6 +38,10 @@ export default class DockerIntegration extends Integration<T> {
 		return 'Docker';
 	}
 
+	static get configSchema() {
+		return configSchema;
+	}
+
 	async getContainerName(label: string, value: string): Promise<string> {
 		if (!this.client) {
 			throw new Error('Docker client is not initialized');
@@ -60,7 +81,7 @@ export default class DockerIntegration extends Integration<T> {
 		// Basic configuration check, the name overrides the container_label
 		// selector because of legacy support.
 		const { container_name, container_label } = this.context;
-		if (container_name.length === 0 && container_label.length === 0) {
+		if (container_name?.length === 0 && container_label.length === 0) {
 			log.error(
 				'config',
 				'Missing a Docker `container_name` or `container_label`',
@@ -94,7 +115,7 @@ export default class DockerIntegration extends Integration<T> {
 
 			try {
 				log.info('config', 'Checking API: %s', fetchU);
-				await fetch(new URL('/v1.30/version', fetchU).href);
+				await fetch(new URL('/v1.44/version', fetchU).href);
 			} catch (error) {
 				log.error('config', 'Failed to connect to Docker API: %s', error);
 				log.debug('config', 'Connection error: %o', error);
@@ -127,7 +148,7 @@ export default class DockerIntegration extends Integration<T> {
 
 		const qp = new URLSearchParams({
 			filters: JSON.stringify(
-				container_name.length > 0
+				container_name != null && container_name.length > 0
 					? { name: [container_name] }
 					: { label: [container_label] },
 			),
@@ -140,7 +161,7 @@ export default class DockerIntegration extends Integration<T> {
 		);
 		const res = await this.client.request({
 			method: 'GET',
-			path: `/v1.30/containers/json?${qp.toString()}`,
+			path: `/v1.44/containers/json?${qp.toString()}`,
 		});
 
 		if (res.statusCode !== 200) {
@@ -151,7 +172,7 @@ export default class DockerIntegration extends Integration<T> {
 
 		const data = (await res.body.json()) as DockerContainer[];
 		if (data.length > 1) {
-			if (container_name.length > 0) {
+			if (container_name != null && container_name.length > 0) {
 				log.error(
 					'config',
 					`Found multiple containers with name ${container_name}`,
@@ -167,7 +188,7 @@ export default class DockerIntegration extends Integration<T> {
 		}
 
 		if (data.length === 0) {
-			if (container_name.length > 0) {
+			if (container_name != null && container_name.length > 0) {
 				log.error(
 					'config',
 					`No container found with the name ${container_name}`,
@@ -193,7 +214,7 @@ export default class DockerIntegration extends Integration<T> {
 		return this.client !== undefined && this.containerId !== undefined;
 	}
 
-	async onConfigChange(client: ApiClient) {
+	async onConfigChange(client: RuntimeApiClient) {
 		if (!this.client) {
 			return;
 		}
@@ -211,7 +232,7 @@ export default class DockerIntegration extends Integration<T> {
 
 			const response = await this.client.request({
 				method: 'POST',
-				path: `/v1.30/containers/${this.containerId}/restart`,
+				path: `/v1.44/containers/${this.containerId}/restart`,
 			});
 
 			if (response.statusCode !== 204) {
@@ -233,14 +254,14 @@ export default class DockerIntegration extends Integration<T> {
 		while (attempts <= this.maxAttempts) {
 			try {
 				log.debug('config', 'Checking Headscale status (attempt %d)', attempts);
-				const status = await client.healthcheck();
+				const status = await client.isHealthy();
 				if (status === false) {
 					throw new Error('Headscale is not running');
 				}
 
 				log.info('config', 'Headscale is up and running');
 				return;
-			} catch (error) {
+			} catch {
 				if (attempts < this.maxAttempts) {
 					attempts++;
 					await setTimeout(1000);

app/server/config/integration/index.ts

@@ -1,5 +1,5 @@
-import { HeadplaneConfig } from '~/server/config/schema';
 import log from '~/utils/log';
+import type { HeadplaneConfig } from '../config-schema';
 import dockerIntegration from './docker';
 import kubernetesIntegration from './kubernetes';
 import procIntegration from './proc';
@@ -47,16 +47,16 @@ function getIntegration(integration: HeadplaneConfig['integration']) {
 
 	if (docker?.enabled) {
 		log.info('config', 'Using Docker integration');
-		return new dockerIntegration(integration?.docker);
+		return new dockerIntegration(integration!.docker!);
 	}
 
 	if (k8s?.enabled) {
 		log.info('config', 'Using Kubernetes integration');
-		return new kubernetesIntegration(integration?.kubernetes);
+		return new kubernetesIntegration(integration!.kubernetes!);
 	}
 
 	if (proc?.enabled) {
 		log.info('config', 'Using Proc integration');
-		return new procIntegration(integration?.proc);
+		return new procIntegration(integration!.proc!);
 	}
 }

app/server/config/integration/kubernetes.ts

@@ -1,12 +1,12 @@
-import { readFile, readdir } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { platform } from 'node:os';
 import { join, resolve } from 'node:path';
 import { kill } from 'node:process';
 import { setTimeout } from 'node:timers/promises';
 import { CoreV1Api, KubeConfig } from '@kubernetes/client-node';
-import { ApiClient } from '~/server/headscale/api-client';
+import { type } from 'arktype';
+import type { RuntimeApiClient } from '~/server/headscale/api/endpoints';
 import log from '~/utils/log';
-import { HeadplaneConfig } from '../schema';
 import { Integration } from './abstract';
 
 // https://github.com/kubernetes-client/javascript/blob/055b83c6504dfd1b2a2d081efd974163c6cbb808/src/config.ts#L40
@@ -15,8 +15,23 @@ const svcCaPath = `${svcRoot}/ca.crt`;
 const svcTokenPath = `${svcRoot}/token`;
 const svcNamespacePath = `${svcRoot}/namespace`;
 
-type T = NonNullable<HeadplaneConfig['integration']>['kubernetes'];
-export default class KubernetesIntegration extends Integration<T> {
+const configSchema = {
+	full: type({
+		enabled: 'boolean',
+		pod_name: 'string',
+		validate_manifest: 'boolean = true',
+	}),
+
+	partial: type({
+		enabled: 'boolean?',
+		pod_name: 'string?',
+		validate_manifest: 'boolean?',
+	}).partial(),
+};
+
+export default class KubernetesIntegration extends Integration<
+	typeof configSchema.full.infer
+> {
 	private pid: number | undefined;
 	private maxAttempts = 10;
 
@@ -24,6 +39,10 @@ export default class KubernetesIntegration extends Integration<T> {
 		return 'Kubernetes (k8s)';
 	}
 
+	static get configSchema() {
+		return configSchema;
+	}
+
 	async isAvailable() {
 		if (platform() !== 'linux') {
 			log.error('config', 'Kubernetes is only available on Linux');
@@ -202,7 +221,7 @@ export default class KubernetesIntegration extends Integration<T> {
 		}
 	}
 
-	async onConfigChange(client: ApiClient) {
+	async onConfigChange(client: RuntimeApiClient) {
 		if (!this.pid) {
 			return;
 		}
@@ -220,14 +239,14 @@ export default class KubernetesIntegration extends Integration<T> {
 		while (attempts <= this.maxAttempts) {
 			try {
 				log.debug('config', 'Checking Headscale status (attempt %d)', attempts);
-				const status = await client.healthcheck();
+				const status = await client.isHealthy();
 				if (status === false) {
 					throw new Error('Headscale is not running');
 				}
 
 				log.info('config', 'Headscale is up and running');
 				return;
-			} catch (error) {
+			} catch {
 				if (attempts < this.maxAttempts) {
 					attempts++;
 					await setTimeout(1000);

app/server/config/integration/proc.ts

@@ -1,15 +1,27 @@
-import { readFile, readdir } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { platform } from 'node:os';
 import { join, resolve } from 'node:path';
 import { kill } from 'node:process';
 import { setTimeout } from 'node:timers/promises';
-import { ApiClient } from '~/server/headscale/api-client';
+import { type } from 'arktype';
+import type { RuntimeApiClient } from '~/server/headscale/api/endpoints';
 import log from '~/utils/log';
-import { HeadplaneConfig } from '../schema';
+import type { HeadplaneConfig } from '../config-schema';
 import { Integration } from './abstract';
 
-type T = NonNullable<HeadplaneConfig['integration']>['proc'];
-export default class ProcIntegration extends Integration<T> {
+const configSchema = {
+	full: type({
+		enabled: 'boolean',
+	}),
+
+	partial: type({
+		enabled: 'boolean?',
+	}).partial(),
+};
+
+export default class ProcIntegration extends Integration<
+	typeof configSchema.full.infer
+> {
 	private pid: number | undefined;
 	private maxAttempts = 10;
 
@@ -17,6 +29,10 @@ export default class ProcIntegration extends Integration<T> {
 		return 'Native Linux (/proc)';
 	}
 
+	static get configSchema() {
+		return configSchema;
+	}
+
 	async isAvailable() {
 		if (platform() !== 'linux') {
 			log.error('config', '/proc is only available on Linux');
@@ -68,30 +84,37 @@ export default class ProcIntegration extends Integration<T> {
 					pids.join(', '),
 				);
 
-        log.debug('config', 'Checking if any of them have Parent PID = 1, assuming thats the correct PID');
-        const ppidRegex = /(?:PPid:\s)(\d+)(?:\n?)/;
-        for (const pid of pids) {
-          const pidStatusPath = join('/proc', pid.toString(), 'status');
-          try {
-            log.debug('config', 'Reading %s', pidStatusPath);
-            const pidData = await readFile(pidStatusPath, 'utf8');
-            const ppidResult = pidData.match(ppidRegex);
+				log.debug(
+					'config',
+					'Checking if any of them have Parent PID = 1, assuming thats the correct PID',
+				);
+				const ppidRegex = /(?:PPid:\s)(\d+)(?:\n?)/;
+				for (const pid of pids) {
+					const pidStatusPath = join('/proc', pid.toString(), 'status');
+					try {
+						log.debug('config', 'Reading %s', pidStatusPath);
+						const pidData = await readFile(pidStatusPath, 'utf8');
+						const ppidResult = pidData.match(ppidRegex);
 
-            if (ppidResult !== null) {
-              const potentialPPid = Number.parseInt(ppidResult[1], 10);
-              if (potentialPPid === 1) {
-                this.pid = pid;
-                log.info('config', 'Found potential Headscale process with PID: %d based on Parent PID = 1', this.pid);
-                return true;
-              }
-            }
-          } catch (error) {
-            log.error('config', 'Failed to read %s: %s', pidStatusPath, error);
-          }
-        }
+						if (ppidResult !== null) {
+							const potentialPPid = Number.parseInt(ppidResult[1], 10);
+							if (potentialPPid === 1) {
+								this.pid = pid;
+								log.info(
+									'config',
+									'Found potential Headscale process with PID: %d based on Parent PID = 1',
+									this.pid,
+								);
+								return true;
+							}
+						}
+					} catch (error) {
+						log.error('config', 'Failed to read %s: %s', pidStatusPath, error);
+					}
+				}
 
-        return false;
-      }
+				return false;
+			}
 
 			if (pids.length === 0) {
 				log.error('config', 'Could not find Headscale process');
@@ -107,7 +130,7 @@ export default class ProcIntegration extends Integration<T> {
 		}
 	}
 
-	async onConfigChange(client: ApiClient) {
+	async onConfigChange(client: RuntimeApiClient) {
 		if (!this.pid) {
 			return;
 		}
@@ -125,7 +148,7 @@ export default class ProcIntegration extends Integration<T> {
 		while (attempts <= this.maxAttempts) {
 			try {
 				log.debug('config', 'Checking Headscale status (attempt %d)', attempts);
-				const status = await client.healthcheck();
+				const status = await client.isHealthy();
 				if (status === false) {
 					log.error('config', 'Headscale is not running');
 					return;
@@ -133,7 +156,7 @@ export default class ProcIntegration extends Integration<T> {
 
 				log.info('config', 'Headscale is up and running');
 				return;
-			} catch (error) {
+			} catch {
 				if (attempts < this.maxAttempts) {
 					attempts++;
 					await setTimeout(1000);

app/server/config/load.ts

@@ -0,0 +1,267 @@
+import { access, constants, readFile } from 'node:fs/promises';
+import { type } from 'arktype';
+import { load } from 'js-yaml';
+import log from '~/utils/log';
+import {
+	headplaneConfig,
+	PartialHeadplaneConfig,
+	partialHeadplaneConfig,
+	pathSupportedKeys,
+} from './config-schema';
+import { ConfigError } from './error';
+
+/**
+ * Main entrypoint that attempts to load and merge configuration from both
+ * a YAML config file (if available) and environment variables. Importantly,
+ * the environment variables will override any values set in the config file.
+ *
+ * The function also supports loading secret values from file paths for
+ * specific configuration keys (e.g., certificates, private keys) by checking
+ * for corresponding `_path` suffixed environment variables or config file
+ * entries.
+ *
+ * @param configPathOverride Used for testing to override the config file path
+ * @returns @ref{HeadplaneConfig} The fully validated configuration
+ * @throws {Error} If there are validation errors in the final configuration
+ */
+export async function loadConfig(configPathOverride?: string) {
+	const configPath =
+		configPathOverride != null
+			? configPathOverride
+			: process.env.HEADPLANE_CONFIG_PATH != null
+				? String(process.env.HEADPLANE_CONFIG_PATH)
+				: '/etc/headplane/config.yaml';
+
+	const fileConfig = await loadConfigFile(configPath);
+	const envConfig = await loadConfigEnv();
+
+	const combinedConfig = deepMerge(fileConfig, envConfig);
+	await loadConfigKeyPaths(combinedConfig);
+
+	const finalConfig = headplaneConfig(combinedConfig);
+	if (finalConfig instanceof type.errors) {
+		throw ConfigError.from('INVALID_REQUIRED_FIELDS', {
+			messages: finalConfig.map((e) => e.toString()),
+		});
+	}
+
+	return finalConfig;
+}
+
+/**
+ * Attempts to load configuration from a YAML file at the specified path.
+ * If the file is not accessible, it returns undefined.
+ *
+ * @param path The file path to load the configuration from
+ * @returns A partial configuration object or undefined
+ * @throws {Error} If there are validation errors in the loaded configuration
+ */
+export async function loadConfigFile(path: string) {
+	try {
+		await access(path, constants.R_OK);
+	} catch {
+		log.info('config', 'Could not access config file at path: %s', path);
+		return;
+	}
+
+	const rawBuffer = await readFile(path, 'utf8');
+	const rawConfig = load(rawBuffer);
+	const config = partialHeadplaneConfig(rawConfig);
+	if (config instanceof type.errors) {
+		throw ConfigError.from('INVALID_REQUIRED_FIELDS', {
+			messages: config.map((e) => e.toString()),
+		});
+	}
+
+	return config;
+}
+
+/**
+ * Loads configuration overrides from environment variables prefixed with
+ * `HEADPLANE_`. Nested configuration keys can be represented using double
+ * underscores (`__`). For example, `HEADPLANE_SERVER__PORT=8080` would set
+ * the `server.port` configuration key to `8080`.
+ *
+ * @returns A partial configuration object or undefined
+ * @throws {Error} If there are validation errors in the loaded configuration
+ */
+export async function loadConfigEnv() {
+	if (process.env.HEADPLANE_LOAD_ENV_OVERRIDES != null) {
+		log.warn(
+			'config',
+			'HEADPLANE_LOAD_ENV_OVERRIDES is deprecated and will be removed in future versions',
+		);
+		log.warn(
+			'config',
+			'Environment variables are always loaded and `.env` files are no longer supported',
+		);
+	}
+
+	const rawConfig: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(process.env)) {
+		if (value == null || !key.startsWith('HEADPLANE_')) {
+			continue;
+		}
+
+		const parsedValue = parseEnvValue(value);
+		const configKey = key.slice('HEADPLANE_'.length).toLowerCase();
+		deepSet(rawConfig, configKey.split('__'), parsedValue);
+	}
+
+	const config = partialHeadplaneConfig(rawConfig);
+	if (config instanceof type.errors) {
+		throw ConfigError.from('INVALID_REQUIRED_FIELDS', {
+			messages: config.map((e) => e.toString()),
+		});
+	}
+
+	return Object.keys(config).length > 0 ? config : undefined;
+}
+
+/**
+ * Deeply merges multiple objects together. Later objects in the arguments
+ * list will override properties of earlier objects.
+ *
+ * @param objects The objects to merge
+ * @returns The merged object
+ */
+function deepMerge<T>(...objects: (T | undefined)[]): T {
+	const result: { [key: string]: unknown } = {};
+	for (const obj of objects.filter((o) => o != null)) {
+		for (const [key, value] of Object.entries(
+			obj as {
+				[key: string]: unknown;
+			},
+		)) {
+			if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+				if (
+					result[key] == null ||
+					typeof result[key] !== 'object' ||
+					Array.isArray(result[key])
+				) {
+					result[key] = {};
+				}
+				result[key] = deepMerge(result[key], value);
+			} else {
+				result[key] = value;
+			}
+		}
+	}
+
+	return result as T;
+}
+
+/**
+ * Sets a value deeply within an object based on the provided path.
+ *
+ * @param obj The object to set the value in
+ * @param path An array of keys representing the path to set
+ * @param value The value to set at the specified path
+ */
+function deepSet(
+	obj: { [key: string]: unknown },
+	path: string[],
+	value: unknown,
+): void {
+	let current = obj;
+	for (let i = 0; i < path.length - 1; i++) {
+		const key = path[i];
+		if (current[key] == null || typeof current[key] !== 'object') {
+			current[key] = {};
+		}
+
+		current = current[key] as { [key: string]: unknown };
+	}
+
+	current[path[path.length - 1]] = value;
+}
+
+/**
+ * Parses an environment variable string value into an appropriate type.
+ * Supports booleans, null, undefined, and numbers. Falls back to string.
+ *
+ * @param value The environment variable string value
+ * @returns The parsed value
+ */
+function parseEnvValue(value: string): unknown {
+	const v = value.trim().toLowerCase();
+	if (v === 'true') return true;
+	if (v === 'false') return false;
+	if (v === 'null') return null;
+	if (v === 'undefined') return undefined;
+
+	if (/^-?\d+(\.\d+)?$/.test(v)) {
+		const num = Number(v);
+		if (!Number.isNaN(num)) return num;
+	}
+
+	return value;
+}
+
+/**
+ * For configuration keys that support loading from file paths (e.g.,
+ * certificates, private keys), this function checks for corresponding
+ * `_path` suffixed keys and loads the file content if the main key is
+ * not already set.
+ *
+ * @param partial The partial configuration object to update
+ */
+export async function loadConfigKeyPaths(partial: PartialHeadplaneConfig) {
+	for (const key of pathSupportedKeys) {
+		const pathKey = `${key}_path`;
+		const pathValue = deepGet(partial, pathKey.split('.'));
+		const existing = deepGet(partial, key.split('.'));
+
+		if (pathValue == null || typeof pathValue !== 'string') {
+			continue;
+		}
+
+		if (existing != null) {
+			throw ConfigError.from('CONFLICTING_SECRET_PATH_FIELD', {
+				fieldName: key,
+			});
+		}
+
+		const realPath = pathValue.replace(/\$\{([^}]+)\}/g, (_, variableName) => {
+			const value = process.env[variableName];
+			if (value === undefined) {
+				throw ConfigError.from('MISSING_INTERPOLATION_VARIABLE', {
+					pathKey: `${key}_path`,
+					variableName: variableName,
+				});
+			}
+
+			return value;
+		});
+
+		try {
+			const fileContent = await readFile(realPath, 'utf8');
+			deepSet(partial, key.split('.'), fileContent.trim().normalize());
+		} catch {
+			throw ConfigError.from('MISSING_SECRET_FILE', {
+				pathKey: `${key}_path`,
+				filePath: realPath,
+			});
+		}
+	}
+}
+
+/**
+ * Deeply retrieves a value from an object based on the provided path.
+ *
+ * @param obj The object to retrieve the value from
+ * @param path An array of keys representing the path to retrieve
+ * @returns The value at the specified path or undefined if not found
+ */
+function deepGet(obj: { [key: string]: unknown }, path: string[]): unknown {
+	let current = obj;
+	for (const segment of path) {
+		if (current == null || typeof current !== 'object') {
+			return undefined;
+		}
+
+		current = current[segment] as { [key: string]: unknown };
+	}
+
+	return current;
+}

app/server/config/loader.ts

@@ -1,303 +0,0 @@
-import { access, constants, readFile } from 'node:fs/promises';
-import { env } from 'node:process';
-import { type } from 'arktype';
-import { configDotenv } from 'dotenv';
-import { parseDocument } from 'yaml';
-import log from '~/utils/log';
-import { EnvOverrides, envVariables } from './env';
-import {
-	HeadplaneConfig,
-	headplaneConfig,
-	partialHeadplaneConfig,
-} from './schema';
-
-// Custom error for config issues
-export class ConfigError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = 'ConfigError';
-	}
-}
-
-/**
- * Interpolate environment variables in a string
- * Replaces ${VAR_NAME} patterns with the actual environment variable values
- */
-export function interpolateEnvVars(str: string): string {
-	return str.replace(/\$\{([^}]+)\}/g, (_, varName) => {
-		const value = env[varName];
-		if (value === undefined) {
-			throw new ConfigError(`Environment variable "${varName}" not found`);
-		}
-		return value;
-	});
-}
-
-// loadConfig is a has a lifetime of the entire application and is
-// used to load the configuration for Headplane. It is called once.
-//
-// TODO: Potential for file watching on the configuration
-// But this may not be necessary as a use-case anyways
-export async function loadConfig({ loadEnv, path }: EnvOverrides) {
-	log.debug('config', 'Loading configuration file: %s', path);
-	await validateConfigPath(path);
-
-	const data = await loadConfigFile(path);
-	if (!data) {
-		throw new ConfigError('Failed to load configuration file');
-	}
-
-	let config = validateConfig({ ...data, debug: log.debugEnabled });
-
-	if (!loadEnv) {
-		log.debug('config', 'Environment variable overrides are disabled');
-		log.debug('config', 'This also disables the loading of a .env file');
-		const moddedConfig = await loadSecretsFromFiles(config);
-		log.debug('config', 'Loaded file-based secrets');
-		return moddedConfig;
-	}
-
-	log.info('config', 'Loading a .env file (if available)');
-	configDotenv({ override: true, quiet: true });
-	const merged = coalesceEnv(config);
-	if (merged) config = merged;
-	if (config.headscale && typeof config.headscale.config_path === 'string') {
-		config.headscale.config_path = interpolateEnvVars(
-			config.headscale.config_path,
-		);
-	}
-
-	const moddedConfig = await loadSecretsFromFiles(config);
-	log.debug('config', 'Loaded file-based secrets');
-
-	return moddedConfig;
-}
-
-/**
- * Recursively walks the config object; for any key in the whitelist of secret path keys,
- * reads that file and assigns its contents to the corresponding key
- * without the suffix, then removes the "_path" property.
- */
-const SECRET_PATH_KEYS = [
-	'pre_authkey_path',
-	'client_secret_path',
-	'headscale_api_key_path',
-	'cookie_secret_path',
-] as const;
-
-// For fast set hashing lookups, but we still need the array for typings
-const SECRET_PATH_KEY_SET = new Set<string>(SECRET_PATH_KEYS);
-
-type SecretPathKey = (typeof SECRET_PATH_KEYS)[number];
-type StripPath<S extends string> = S extends `${infer T}_path` ? T : never;
-type KeysToPromote<T> = Extract<keyof T & string, SecretPathKey>;
-type MappedKeys<T> = StripPath<KeysToPromote<T>>;
-
-type NonNullablized<T> = Omit<T, KeysToPromote<T> | MappedKeys<T>> & {
-	[K in MappedKeys<T>]-?: string;
-};
-
-type NestedNonNullablized<T> = T extends readonly (infer U)[]
-	? readonly NestedNonNullablized<U>[]
-	: T extends (infer U)[]
-		? NestedNonNullablized<U>[]
-		: T extends object
-			? {
-					[K in keyof NonNullablized<T>]: NestedNonNullablized<
-						NonNullablized<T>[K]
-					>;
-				}
-			: T;
-
-async function loadSecretsFromFiles<T extends object>(
-	obj: T,
-): Promise<NestedNonNullablized<T>> {
-	// Work with a Record so we can mutate/delete properties
-	const record = obj as Record<string, unknown>;
-
-	for (const key of Object.keys(record)) {
-		const val = record[key];
-
-		if (val && typeof val === 'object') {
-			// recurse into nested objects
-			record[key] = await loadSecretsFromFiles(val);
-			continue;
-		}
-
-		if (SECRET_PATH_KEY_SET.has(key) && typeof val === 'string') {
-			try {
-				const path = interpolateEnvVars(val);
-				const content = await readFile(path, 'utf8');
-				const secretKey = key.slice(0, -5); // drop '_path'
-				record[secretKey] = content.trim();
-				delete record[key];
-				log.debug('config', 'Loaded secret from %s → %s', val, secretKey);
-			} catch (err) {
-				if (err instanceof ConfigError) throw err;
-				log.error('config', 'Failed to read secret file %s: %s', val, err);
-				throw new ConfigError(`Failed to read secret file ${val}: ${err}`);
-			}
-		}
-	}
-
-	// Cast back to the original T so callers keep their precise type
-	return record as NestedNonNullablized<T>;
-}
-
-async function validateConfigPath(path: string) {
-	try {
-		await access(path, constants.F_OK | constants.R_OK);
-		log.info('config', 'Found a valid configuration file at %s', path);
-		return true;
-	} catch (error) {
-		log.error('config', 'Unable to read a configuration file at %s', path);
-		log.error('config', '%s', error);
-		throw new ConfigError(
-			`Unable to read configuration file at ${path}: ${error}`,
-		);
-	}
-}
-
-async function loadConfigFile(path: string): Promise<unknown> {
-	log.debug('config', 'Reading configuration file at %s', path);
-	try {
-		const data = await readFile(path, 'utf8');
-		const configYaml = parseDocument(data);
-		if (configYaml.errors.length > 0) {
-			log.error('config', 'Cannot parse configuration file at %s', path);
-			for (const error of configYaml.errors) {
-				log.error('config', ` - ${error.toString()}`);
-			}
-
-			throw new ConfigError(`Cannot parse configuration file at ${path}`);
-		}
-
-		if (configYaml.warnings.length > 0) {
-			log.warn(
-				'config',
-				'Warnings while parsing configuration file at %s',
-				path,
-			);
-			for (const warning of configYaml.warnings) {
-				log.warn('config', ` - ${warning.toString()}`);
-			}
-		}
-
-		return configYaml.toJSON() as unknown;
-	} catch (e) {
-		log.error('config', 'Error reading configuration file at %s', path);
-		log.error('config', '%s', e);
-		throw new ConfigError(`Error reading configuration file at ${path}: ${e}`);
-	}
-}
-
-export function validateConfig(config: unknown) {
-	log.debug('config', 'Validating Headplane configuration');
-	const result = headplaneConfig(config);
-	if (result instanceof type.errors) {
-		const errorMessages = [];
-		for (const [number, error] of result.entries()) {
-			const errorMsg = error.toString();
-			log.error('config', ` - (${number}): ${errorMsg}`);
-			errorMessages.push(errorMsg);
-		}
-		throw new ConfigError(errorMessages.join('\n'));
-	}
-	return result;
-}
-
-function coalesceEnv(config: HeadplaneConfig) {
-	const envConfig: Record<string, unknown> = {};
-	const rootKeys: string[] = Object.values(envVariables);
-
-	// Typescript is still insanely stupid at nullish filtering
-	const vars = Object.entries(env).filter(([key, value]) => {
-		if (!value) {
-			return false;
-		}
-
-		if (!key.startsWith('HEADPLANE_')) {
-			return false;
-		}
-
-		// Filter out the rootEnv configurations
-		if (rootKeys.includes(key)) {
-			return false;
-		}
-
-		return true;
-	}) as [string, string][];
-
-	log.debug('config', 'Coalescing %s environment variables', vars.length);
-	for (const [key, value] of vars) {
-		const configPath = key.replace('HEADPLANE_', '').toLowerCase().split('__');
-		log.debug(
-			'config',
-			` - ${key}=${new Array(value.length).fill('*').join('')}`,
-		);
-
-		let current = envConfig;
-		while (configPath.length > 1) {
-			const path = configPath.shift() as string;
-			if (!(path in current)) {
-				current[path] = {};
-			}
-
-			current = current[path] as Record<string, unknown>;
-		}
-
-		current[configPath[0]] = value;
-	}
-
-	const toMerge = coalesceConfig(envConfig);
-	if (!toMerge) {
-		return;
-	}
-
-	// Deep merge the environment variables into the configuration
-	// This will overwrite any existing values in the configuration
-	return deepMerge(config, toMerge);
-}
-
-export function coalesceConfig(config: unknown) {
-	log.debug('config', 'Revalidating config after coalescing variables');
-	const out = partialHeadplaneConfig(config);
-	if (out instanceof type.errors) {
-		log.error('config', 'Error parsing variables:');
-		for (const [number, error] of out.entries()) {
-			log.error('config', ` - (${number}): ${error.toString()}`);
-		}
-
-		return;
-	}
-
-	return out;
-}
-
-type DeepPartial<T> =
-	| {
-			[P in keyof T]?: DeepPartial<T[P]>;
-	  }
-	| undefined;
-
-function deepMerge<T>(target: T, source: DeepPartial<T>): T {
-	if (typeof target !== 'object' || typeof source !== 'object')
-		return source as T;
-	const result = { ...target } as T;
-
-	for (const key in source) {
-		const val = source[key];
-		if (val === undefined || val === null) {
-			continue;
-		}
-
-		if (typeof val === 'object') {
-			result[key] = deepMerge(result[key], val);
-			continue;
-		}
-
-		result[key] = val;
-	}
-
-	return result;
-}

app/server/config/schema.ts

@@ -1,223 +0,0 @@
-import { type } from 'arktype';
-
-const stringToBool = type('string | boolean').pipe((v) => {
-	if (typeof v === 'string') {
-		if (v === '1' || v === 'true' || v === 'yes') {
-			return true;
-		}
-
-		if (v === '0' || v === 'false' || v === 'no') {
-			return false;
-		}
-
-		throw new Error(`Invalid string value for boolean: ${v}`);
-	}
-
-	return Boolean(v);
-});
-
-const serverConfig = type({
-	host: 'string.ip',
-	port: type('string | number.integer').pipe((v) => Number(v)),
-	data_path: 'string = "/var/lib/headplane/"',
-	cookie_secret: '(32 <= string <= 32)?',
-	cookie_secret_path: 'string?',
-	cookie_secure: stringToBool,
-})
-	.narrow((obj: Record<string, unknown>, ctx: any) => {
-		const hasVal = obj.cookie_secret != null && `${obj.cookie_secret}` !== '';
-		const hasPath =
-			obj.cookie_secret_path != null && obj.cookie_secret_path !== '';
-		if (hasVal && hasPath)
-			return ctx.reject(
-				`Only one of "cookie_secret" or "cookie_secret_path" may be set.`,
-			);
-		if (!hasVal && !hasPath)
-			return ctx.reject(
-				`Either "cookie_secret" or "cookie_secret_path" must be provided for cookie_secret.`,
-			);
-		return true;
-	})
-	.onDeepUndeclaredKey('reject');
-
-const partialServerConfig = type({
-	host: 'string.ip?',
-	port: type('string | number.integer')
-		.pipe((v) => Number(v))
-		.optional(),
-	data_path: 'string = "/var/lib/headplane/"',
-	cookie_secret: '32 <= string <= 32?',
-	cookie_secret_path: 'string?',
-	cookie_secure: stringToBool.optional(),
-});
-
-const oidcConfig = type({
-	issuer: 'string.url',
-	client_id: 'string',
-	client_secret: 'string?',
-	client_secret_path: 'string?',
-	token_endpoint_auth_method:
-		'"client_secret_basic" | "client_secret_post" | "client_secret_jwt"',
-	redirect_uri: 'string.url?',
-	user_storage_file: 'string = "/var/lib/headplane/users.json"',
-	disable_api_key_login: stringToBool,
-	headscale_api_key: 'string?',
-	headscale_api_key_path: 'string?',
-	profile_picture_source: '"oidc" | "gravatar" = "oidc"',
-	strict_validation: stringToBool.default(true),
-	scope: 'string = "openid email profile"',
-	extra_params: 'Record<string, string>?',
-	authorization_endpoint: 'string.url?',
-	token_endpoint: 'string.url?',
-	userinfo_endpoint: 'string.url?',
-})
-	.narrow((obj: Record<string, unknown>, ctx: any) => {
-		const hasVal =
-			obj.headscale_api_key != null && `${obj.headscale_api_key}` !== '';
-		const hasPath =
-			obj.headscale_api_key_path != null && obj.headscale_api_key_path !== '';
-		if (hasVal && hasPath)
-			return ctx.reject(
-				`Only one of "headscale_api_key" or "headscale_api_key_path" may be set.`,
-			);
-		if (!hasVal && !hasPath)
-			return ctx.reject(
-				`Either "headscale_api_key" or "headscale_api_key_path" must be provided.`,
-			);
-		return true;
-	})
-	.onDeepUndeclaredKey('reject');
-
-const partialOidcConfig = type({
-	issuer: 'string.url?',
-	client_id: 'string?',
-	client_secret: 'string?',
-	client_secret_path: 'string?',
-	token_endpoint_auth_method:
-		'"client_secret_basic" | "client_secret_post" | "client_secret_jwt"?',
-	redirect_uri: 'string.url?',
-	user_storage_file: 'string?',
-	disable_api_key_login: stringToBool.optional(),
-	headscale_api_key: 'string?',
-	headscale_api_key_path: 'string?',
-	profile_picture_source: '("oidc" | "gravatar")?',
-	strict_validation: stringToBool.default(true),
-	scope: 'string?',
-	extra_params: 'Record<string, string>?',
-	authorization_endpoint: 'string.url?',
-	token_endpoint: 'string.url?',
-	userinfo_endpoint: 'string.url?',
-});
-
-const headscaleConfig = type({
-	url: type('string.url').pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v)),
-	tls_cert_path: 'string?',
-	public_url: 'string.url?',
-	config_path: 'string?',
-	config_strict: stringToBool,
-	dns_records_path: 'string?',
-}).onDeepUndeclaredKey('reject');
-
-const partialHeadscaleConfig = type({
-	url: type('string.url')
-		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
-		.optional(),
-	tls_cert_path: 'string?',
-	public_url: 'string.url?',
-	config_path: 'string?',
-	config_strict: stringToBool.optional(),
-	dns_records_path: 'string?',
-});
-
-const agentConfig = type({
-	enabled: stringToBool.default(false),
-	host_name: 'string = "headplane-agent"',
-	pre_authkey: 'string?',
-	pre_authkey_path: 'string?',
-	cache_ttl: 'number.integer = 180000',
-	cache_path: 'string = "/var/lib/headplane/agent_cache.json"',
-	executable_path: 'string = "/usr/libexec/headplane/agent"',
-	work_dir: 'string = "/var/lib/headplane/agent"',
-})
-	.narrow((obj: Record<string, unknown>, ctx: any) => {
-		const hasVal = obj.pre_authkey != null && `${obj.pre_authkey}` !== '';
-		const hasPath = obj.pre_authkey_path != null && obj.pre_authkey_path !== '';
-		if (hasVal && hasPath)
-			return ctx.reject(
-				`Only one of "pre_authkey" or "pre_authkey_path" may be set.`,
-			);
-		if (!hasVal && !hasPath)
-			return ctx.reject(
-				`Either "pre_authkey" or "pre_authkey_path" must be provided.`,
-			);
-		return true;
-	})
-	.onDeepUndeclaredKey('reject');
-
-const partialAgentConfig = type({
-	enabled: stringToBool.default(false),
-	host_name: 'string = "headplane-agent"',
-	pre_authkey: 'string?',
-	pre_authkey_path: 'string?',
-	cache_ttl: 'number.integer = 180000',
-	cache_path: 'string = "/var/lib/headplane/agent_cache.json"',
-	executable_path: 'string = "/usr/libexec/headplane/agent"',
-	work_dir: 'string = "/var/lib/headplane/agent"',
-});
-
-const dockerConfig = type({
-	enabled: stringToBool,
-	container_name: 'string = ""',
-	container_label: 'string = "me.tale.headplane.target=headscale"',
-	socket: 'string = "unix:///var/run/docker.sock"',
-});
-
-const partialDockerConfig = type({
-	enabled: stringToBool,
-	container_name: 'string | undefined',
-	container_label: 'string | undefined',
-	socket: 'string | undefined',
-}).partial();
-
-const kubernetesConfig = type({
-	enabled: stringToBool,
-	pod_name: 'string',
-	validate_manifest: stringToBool,
-});
-
-const procConfig = type({
-	enabled: stringToBool,
-});
-
-const integrationConfig = type({
-	'docker?': dockerConfig,
-	'kubernetes?': kubernetesConfig,
-	'proc?': procConfig,
-	'agent?': agentConfig,
-});
-
-const partialIntegrationConfig = type({
-	'docker?': partialDockerConfig,
-	'kubernetes?': kubernetesConfig.partial(),
-	'proc?': procConfig.partial(),
-	'agent?': partialAgentConfig,
-}).partial();
-
-export const headplaneConfig = type({
-	debug: stringToBool,
-	server: serverConfig,
-	'oidc?': oidcConfig,
-	'integration?': integrationConfig,
-	headscale: headscaleConfig,
-}).onDeepUndeclaredKey('delete');
-
-export const partialHeadplaneConfig = type({
-	debug: stringToBool,
-	server: partialServerConfig,
-	'oidc?': partialOidcConfig,
-	'integration?': partialIntegrationConfig,
-	headscale: partialHeadscaleConfig,
-}).partial();
-
-export type HeadplaneConfig = typeof headplaneConfig.infer;
-export type PartialHeadplaneConfig = typeof partialHeadplaneConfig.infer;

app/server/config/utils.ts

@@ -0,0 +1,9 @@
+import type { Traversal } from 'arktype';
+import log from '~/utils/log';
+
+export function deprecatedField() {
+	return (_: unknown, ctx: Traversal) => {
+		log.warn('config', `${ctx.propString} is deprecated and has no effect.`);
+		return true;
+	};
+}

app/server/db/pruner.ts

@@ -1,14 +1,12 @@
 import { eq, isNotNull } from 'drizzle-orm';
-import { LoaderFunctionArgs } from 'react-router';
-import { Machine } from '~/types';
 import log from '~/utils/log';
-import { LoadContext } from '..';
+import type { Route } from '../../layouts/+types/dashboard';
 import { ephemeralNodes } from './schema';
 
 export async function pruneEphemeralNodes({
 	context,
 	request,
-}: LoaderFunctionArgs<LoadContext>) {
+}: Route.LoaderArgs) {
 	const session = await context.sessions.auth(request);
 	const ephemerals = await context.db
 		.select()
@@ -20,11 +18,8 @@ export async function pruneEphemeralNodes({
 		return;
 	}
 
-	const { nodes } = await context.client.get<{ nodes: Machine[] }>(
-		'v1/node',
-		session.api_key,
-	);
-
+	const api = context.hsApi.getRuntimeClient(session.api_key);
+	const nodes = await api.getNodes();
 	const toPrune = nodes.filter((node) => {
 		if (node.online) {
 			return false;
@@ -42,7 +37,7 @@ export async function pruneEphemeralNodes({
 	const promises = toPrune.map((node) => {
 		return async () => {
 			log.debug('api', `Pruning node ${node.name}`);
-			await context.client.delete(`v1/node/${node.id}`, session.api_key);
+			await api.deleteNode(node.id);
 
 			await context.db
 				.delete(ephemeralNodes)

app/server/headscale/api-client.ts

@@ -1,263 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { data } from 'react-router';
-import { Agent, Dispatcher, request } from 'undici';
-import { errors } from 'undici';
-import log from '~/utils/log';
-import ResponseError from './api-error';
-
-function isNodeNetworkError(error: unknown): error is NodeJS.ErrnoException {
-	const keys = Object.keys(error as Record<string, unknown>);
-	return (
-		typeof error === 'object' &&
-		error !== null &&
-		keys.includes('code') &&
-		keys.includes('errno')
-	);
-}
-
-function friendlyError(givenError: unknown) {
-	let error: unknown = givenError;
-	if (error instanceof AggregateError) {
-		error = error.errors[0];
-	}
-
-	switch (true) {
-		case error instanceof errors.BodyTimeoutError:
-		case error instanceof errors.ConnectTimeoutError:
-		case error instanceof errors.HeadersTimeoutError:
-			return data('Timed out waiting for a response from the Headscale API', {
-				statusText: 'Request Timeout',
-				status: 408,
-			});
-
-		case error instanceof errors.SocketError:
-		case error instanceof errors.SecureProxyConnectionError:
-		case error instanceof errors.ClientClosedError:
-		case error instanceof errors.ClientDestroyedError:
-		case error instanceof errors.RequestAbortedError:
-			return data('The Headscale API is not reachable', {
-				statusText: 'Service Unavailable',
-				status: 503,
-			});
-
-		case error instanceof errors.InvalidArgumentError:
-		case error instanceof errors.InvalidReturnValueError:
-		case error instanceof errors.NotSupportedError:
-			return data('Unable to make a request (this is most likely a bug)', {
-				statusText: 'Internal Server Error',
-				status: 500,
-			});
-
-		case error instanceof errors.HeadersOverflowError:
-		case error instanceof errors.RequestContentLengthMismatchError:
-		case error instanceof errors.ResponseContentLengthMismatchError:
-		case error instanceof errors.ResponseExceededMaxSizeError:
-			return data('The Headscale API returned a malformed response', {
-				statusText: 'Bad Gateway',
-				status: 502,
-			});
-
-		case isNodeNetworkError(error):
-			if (error.code === 'ECONNREFUSED') {
-				return data('The Headscale API is not reachable', {
-					statusText: 'Service Unavailable',
-					status: 503,
-				});
-			}
-
-			if (error.code === 'ENOTFOUND') {
-				return data('The Headscale API is not reachable', {
-					statusText: 'Service Unavailable',
-					status: 503,
-				});
-			}
-
-			if (error.code === 'EAI_AGAIN') {
-				return data('The Headscale API is not reachable', {
-					statusText: 'Service Unavailable',
-					status: 503,
-				});
-			}
-
-			if (error.code === 'ETIMEDOUT') {
-				return data('Timed out waiting for a response from the Headscale API', {
-					statusText: 'Request Timeout',
-					status: 408,
-				});
-			}
-
-			if (error.code === 'ECONNRESET') {
-				return data('The Headscale API is not reachable', {
-					statusText: 'Service Unavailable',
-					status: 503,
-				});
-			}
-
-			if (error.code === 'EPIPE') {
-				return data('The Headscale API is not reachable', {
-					statusText: 'Service Unavailable',
-					status: 503,
-				});
-			}
-
-			if (error.code === 'ENETUNREACH') {
-				return data('The Headscale API is not reachable', {
-					statusText: 'Service Unavailable',
-					status: 503,
-				});
-			}
-
-			if (error.code === 'ENETRESET') {
-				return data('The Headscale API is not reachable', {
-					statusText: 'Service Unavailable',
-					status: 503,
-				});
-			}
-
-			return data('The Headscale API is not reachable', {
-				statusText: 'Service Unavailable',
-				status: 503,
-			});
-
-		default:
-			return data((error as Error).message ?? 'An unknown error occurred', {
-				statusText: 'Internal Server Error',
-				status: 500,
-			});
-	}
-}
-
-export async function createApiClient(base: string, certPath?: string) {
-	if (!certPath) {
-		return new ApiClient(new Agent(), base);
-	}
-
-	try {
-		log.debug('config', 'Loading certificate from %s', certPath);
-		const data = await readFile(certPath, 'utf8');
-
-		log.info('config', 'Using certificate from %s', certPath);
-		return new ApiClient(new Agent({ connect: { ca: data.trim() } }), base);
-	} catch (error) {
-		log.error('config', 'Failed to load Headscale TLS cert: %s', error);
-		log.debug('config', 'Error Details: %o', error);
-		return new ApiClient(new Agent(), base);
-	}
-}
-
-export class ApiClient {
-	private agent: Agent;
-	private base: string;
-
-	constructor(agent: Agent, base: string) {
-		this.agent = agent;
-		this.base = base;
-	}
-
-	private async defaultFetch(
-		url: string,
-		options?: Partial<Dispatcher.RequestOptions>,
-	) {
-		const method = options?.method ?? 'GET';
-		log.debug('api', '%s %s', method, url);
-
-		try {
-			const res = await request(new URL(url, this.base), {
-				dispatcher: this.agent,
-				headers: {
-					...options?.headers,
-					Accept: 'application/json',
-					'User-Agent': `Headplane/${__VERSION__}`,
-				},
-				body: options?.body,
-				method,
-			});
-
-			return res;
-		} catch (error: unknown) {
-			throw friendlyError(error);
-		}
-	}
-
-	async healthcheck() {
-		try {
-			const res = await request(new URL('/health', this.base), {
-				dispatcher: this.agent,
-				headers: {
-					Accept: 'application/json',
-					'User-Agent': `Headplane/${__VERSION__}`,
-				},
-			});
-
-			return res.statusCode === 200;
-		} catch (error) {
-			log.debug('api', 'Healthcheck failed %o', error);
-			return false;
-		}
-	}
-
-	async get<T = unknown>(url: string, key: string) {
-		const res = await this.defaultFetch(`/api/${url}`, {
-			headers: {
-				Authorization: `Bearer ${key}`,
-			},
-		});
-
-		if (res.statusCode >= 400) {
-			log.debug('api', 'GET %s failed with status %d', url, res.statusCode);
-			throw new ResponseError(res.statusCode, await res.body.text());
-		}
-
-		return res.body.json() as Promise<T>;
-	}
-
-	async post<T = unknown>(url: string, key: string, body?: unknown) {
-		const res = await this.defaultFetch(`/api/${url}`, {
-			method: 'POST',
-			body: body ? JSON.stringify(body) : undefined,
-			headers: {
-				Authorization: `Bearer ${key}`,
-			},
-		});
-
-		if (res.statusCode >= 400) {
-			log.debug('api', 'POST %s failed with status %d', url, res.statusCode);
-			throw new ResponseError(res.statusCode, await res.body.text());
-		}
-
-		return res.body.json() as Promise<T>;
-	}
-
-	async put<T = unknown>(url: string, key: string, body?: unknown) {
-		const res = await this.defaultFetch(`/api/${url}`, {
-			method: 'PUT',
-			body: body ? JSON.stringify(body) : undefined,
-			headers: {
-				Authorization: `Bearer ${key}`,
-			},
-		});
-
-		if (res.statusCode >= 400) {
-			log.debug('api', 'PUT %s failed with status %d', url, res.statusCode);
-			throw new ResponseError(res.statusCode, await res.body.text());
-		}
-
-		return res.body.json() as Promise<T>;
-	}
-
-	async delete<T = unknown>(url: string, key: string) {
-		const res = await this.defaultFetch(`/api/${url}`, {
-			method: 'DELETE',
-			headers: {
-				Authorization: `Bearer ${key}`,
-			},
-		});
-
-		if (res.statusCode >= 400) {
-			log.debug('api', 'DELETE %s failed with status %d', url, res.statusCode);
-			throw new ResponseError(res.statusCode, await res.body.text());
-		}
-
-		return res.body.json() as Promise<T>;
-	}
-}

app/server/headscale/api-error.ts

@@ -1,19 +0,0 @@
-// Represents an error that occurred during a response
-// Thrown when status codes are >= 400
-export default class ResponseError extends Error {
-	status: number;
-	response: string;
-	responseObject?: Record<string, unknown>;
-
-	constructor(status: number, response: string) {
-		super(`Response Error (${status}): ${response}`);
-		this.name = 'ResponseError';
-		this.status = status;
-		this.response = response;
-
-		try {
-			// Try to parse the response as JSON to get a response object
-			this.responseObject = JSON.parse(response);
-		} catch {}
-	}
-}

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

@@ -0,0 +1,23 @@
+import type { Key } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface ApiKeyEndpoints {
+	/**
+	 * Retrieves all API keys from the Headscale instance.
+	 *
+	 * @returns An array of `Key` objects representing the API keys.
+	 */
+	getApiKeys(): Promise<Key[]>;
+}
+
+export default defineApiEndpoints<ApiKeyEndpoints>((client, apiKey) => ({
+	getApiKeys: async () => {
+		const { apiKeys } = await client.apiFetch<{ apiKeys: Key[] }>(
+			'GET',
+			'v1/apikey',
+			apiKey,
+		);
+
+		return apiKeys;
+	},
+}));

app/server/headscale/api/endpoints/index.ts

@@ -0,0 +1,79 @@
+import {
+	composeEndpoints,
+	defineApiEndpoints,
+	type ExtractApiEndpoints,
+	type UnionToIntersection,
+} from '../factory';
+import type { HeadscaleApiInterface } from '../index';
+import apiKeyEndpoints from './api-keys';
+import nodeEndpoints from './nodes';
+import policyEndpoints from './policy';
+import preAuthKeyEndpoints from './pre-auth-keys';
+import userEndpoints from './users';
+
+interface HealthcheckEndpoint {
+	/**
+	 * Checks if the Headscale instance is healthy.
+	 *
+	 * @returns A boolean indicating if the instance is healthy.
+	 */
+	isHealthy(): Promise<boolean>;
+}
+
+const healthcheckEndpoint = defineApiEndpoints<HealthcheckEndpoint>(
+	(client, apiKey) => ({
+		isHealthy: async () => {
+			try {
+				const res = await client.rawFetch('/health', {
+					method: 'GET',
+					headers: {
+						// This doesn't really matter
+						Authorization: `Bearer ${apiKey}`,
+					},
+				});
+
+				return res.statusCode === 200;
+			} catch {
+				return false;
+			}
+		},
+	}),
+);
+
+/**
+ * A constant list of all endpoint groups.
+ * Add new endpoint groups here.
+ */
+export const endpointSets = [
+	apiKeyEndpoints,
+	healthcheckEndpoint,
+	nodeEndpoints,
+	policyEndpoints,
+	preAuthKeyEndpoints,
+	userEndpoints,
+] as const;
+
+/**
+ * All of the available API methods when interacting with Headscale's API.
+ * We have wrapped each operation with nice methods and parameters to make it
+ * easier to do integration testing by spinning up an actual Headscale instance
+ * and calling these methods against it.
+ *
+ * We also have the benefit of supporting multiple Headscale versions by
+ * passing in different internal implementations based on the OpenAPI spec.
+ */
+export type RuntimeApiClient = UnionToIntersection<
+	ExtractApiEndpoints<(typeof endpointSets)[number]>
+>;
+
+/**
+ * Composes all endpoint groups into a single runtime API client.
+ *
+ * @param client - The client helpers for making API requests.
+ * @param apiKey - The API key for authentication.
+ * @returns A fully composed runtime API client.
+ */
+export default (
+	client: HeadscaleApiInterface['clientHelpers'],
+	apiKey: string,
+) => composeEndpoints(endpointSets, client, apiKey);

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

@@ -0,0 +1,150 @@
+import type { Machine } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface NodeEndpoints {
+	/**
+	 * Retrieves all nodes (machines) from the Headscale instance.
+	 *
+	 * @returns An array of `Machine` objects representing the nodes.
+	 */
+	getNodes(): Promise<Machine[]>;
+
+	/**
+	 * Retrieves a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to retrieve.
+	 * @returns A `Machine` object representing the node.
+	 */
+	getNode(id: string): Promise<Machine>;
+
+	/**
+	 * Deletes a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to delete.
+	 */
+	deleteNode(id: string): Promise<void>;
+
+	/**
+	 * Registers a new node (machine) with the given user and key.
+	 *
+	 * @param user The user to associate with the node.
+	 * @param key The registration key for the node.
+	 * @returns A `Machine` object representing the newly registered node.
+	 */
+	registerNode(user: string, key: string): Promise<Machine>;
+
+	/**
+	 * Approves routes for a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node.
+	 * @param routes An array of routes to approve for the node.
+	 */
+	approveNodeRoutes(id: string, routes: string[]): Promise<void>;
+
+	/**
+	 * Expires a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to expire.
+	 */
+	expireNode(id: string): Promise<void>;
+
+	/**
+	 * Renames a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to rename.
+	 * @param newName The new name for the node.
+	 */
+	renameNode(id: string, newName: string): Promise<void>;
+
+	/**
+	 * Sets tags for a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node.
+	 * @param tags An array of tags to set for the node.
+	 */
+	setNodeTags(id: string, tags: string[]): Promise<void>;
+
+	/**
+	 * Sets the user for a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node.
+	 * @param user The user to set for the node.
+	 */
+	setNodeUser(id: string, user: string): Promise<void>;
+}
+
+export default defineApiEndpoints<NodeEndpoints>((client, apiKey) => ({
+	getNodes: async () => {
+		const { nodes } = await client.apiFetch<{ nodes: Machine[] }>(
+			'GET',
+			'v1/node',
+			apiKey,
+		);
+
+		return nodes;
+	},
+
+	getNode: async (nodeId) => {
+		const { node } = await client.apiFetch<{ node: Machine }>(
+			'GET',
+			`v1/node/${nodeId}`,
+			apiKey,
+		);
+
+		return node;
+	},
+
+	deleteNode: async (nodeId) => {
+		await client.apiFetch<void>('DELETE', `v1/node/${nodeId}`, apiKey);
+	},
+
+	registerNode: async (user, key) => {
+		const qp = new URLSearchParams();
+		qp.append('user', user);
+		qp.append('key', key);
+		const { node } = await client.apiFetch<{ node: Machine }>(
+			'POST',
+			`v1/node/register?${qp.toString()}`,
+			apiKey,
+			{
+				user,
+				key,
+			},
+		);
+
+		return node;
+	},
+
+	approveNodeRoutes: async (nodeId, routes) => {
+		await client.apiFetch<void>(
+			'POST',
+			`v1/node/${nodeId}/approve_routes`,
+			apiKey,
+			{ routes },
+		);
+	},
+
+	expireNode: async (nodeId) => {
+		await client.apiFetch<void>('POST', `v1/node/${nodeId}/expire`, apiKey);
+	},
+
+	renameNode: async (nodeId, newName) => {
+		await client.apiFetch<void>(
+			'POST',
+			`v1/node/${nodeId}/rename/${newName}`,
+			apiKey,
+		);
+	},
+
+	setNodeTags: async (nodeId, tags) => {
+		await client.apiFetch<void>('POST', `v1/node/${nodeId}/tags`, apiKey, {
+			tags,
+		});
+	},
+
+	setNodeUser: async (nodeId, user) => {
+		await client.apiFetch<void>('POST', `v1/node/${nodeId}/user`, apiKey, {
+			user,
+		});
+	},
+}));

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

@@ -0,0 +1,41 @@
+import { defineApiEndpoints } from '../factory';
+
+export interface PolicyEndpoints {
+	/**
+	 * Retrieves the current ACL policy from the Headscale instance.
+	 *
+	 * @returns The ACL policy as a string and the date it was last updated.
+	 */
+	getPolicy(): Promise<{ policy: string; updatedAt: Date | null }>;
+
+	/**
+	 * Sets the ACL policy for the Headscale instance.
+	 *
+	 * @param policy The ACL policy as a string.
+	 * @returns The updated ACL policy as a string and the date it was last updated.
+	 */
+	setPolicy(policy: string): Promise<{ policy: string; updatedAt: Date }>;
+}
+
+export default defineApiEndpoints<PolicyEndpoints>((client, apiKey) => ({
+	getPolicy: async () => {
+		const { policy, updatedAt } = await client.apiFetch<{
+			policy: string;
+			updatedAt: string;
+		}>('GET', 'v1/policy', apiKey);
+
+		return {
+			policy,
+			updatedAt: updatedAt !== null ? new Date(updatedAt) : null,
+		};
+	},
+
+	setPolicy: async (policy) => {
+		const { policy: newPolicy, updatedAt } = await client.apiFetch<{
+			policy: string;
+			updatedAt: string;
+		}>('PUT', 'v1/policy', apiKey, { policy });
+
+		return { policy: newPolicy, updatedAt: new Date(updatedAt) };
+	},
+}));

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

@@ -0,0 +1,69 @@
+import type { PreAuthKey } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface PreAuthKeyEndpoints {
+	/**
+	 * Retrieves all pre-authentication keys for a specific user.
+	 *
+	 * @param user The user to retrieve pre-authentication keys for.
+	 * @returns An array of `PreAuthKey` objects representing the pre-authentication keys.
+	 */
+	getPreAuthKeys(user: string): Promise<PreAuthKey[]>;
+
+	/**
+	 * Creates a new pre-authentication key for a specific user.
+	 *
+	 * @param user The user to create the pre-authentication key for.
+	 * @param ephemeral Whether the key is ephemeral.
+	 * @param reusable Whether the key is reusable.
+	 * @param expiration The expiration date of the key, or `null` for no expiration.
+	 * @param aclTags An array of ACL tags to associate with the key, or `null` for none.
+	 * @returns A `PreAuthKey` object representing the newly created pre-authentication key.
+	 */
+	createPreAuthKey(
+		user: string,
+		ephemeral: boolean,
+		reusable: boolean,
+		expiration: Date | null,
+		aclTags: string[] | null,
+	): Promise<PreAuthKey>;
+
+	/**
+	 * Expires a specific pre-authentication key for a user.
+	 *
+	 * @param user The user associated with the pre-authentication key.
+	 * @param key The pre-authentication key to expire.
+	 */
+	expirePreAuthKey(user: string, key: string): Promise<void>;
+}
+
+export default defineApiEndpoints<PreAuthKeyEndpoints>((client, apiKey) => ({
+	getPreAuthKeys: async (user) => {
+		const { preAuthKeys } = await client.apiFetch<{
+			preAuthKeys: PreAuthKey[];
+		}>('GET', 'v1/preauthkey', apiKey, { user });
+
+		return preAuthKeys;
+	},
+
+	createPreAuthKey: async (user, ephemeral, reusable, expiration, aclTags) => {
+		const { preAuthKey } = await client.apiFetch<{
+			preAuthKey: PreAuthKey;
+		}>('POST', 'v1/preauthkey', apiKey, {
+			user,
+			ephemeral,
+			reusable,
+			expiration: expiration ? expiration.toISOString() : null,
+			aclTags,
+		});
+
+		return preAuthKey;
+	},
+
+	expirePreAuthKey: async (user, key) => {
+		await client.apiFetch<void>('POST', 'v1/preauthkey/expire', apiKey, {
+			user,
+			key,
+		});
+	},
+}));

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

@@ -0,0 +1,88 @@
+import type { User } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface UserEndpoints {
+	/**
+	 * Retrieves users from the Headscale instance, optionally filtering by ID, name, or email.
+	 *
+	 * @param id Optional ID of the user to retrieve.
+	 * @param name Optional name of the user to retrieve.
+	 * @param email Optional email of the user to retrieve.
+	 * @returns An array of `User` objects representing the users.
+	 */
+	getUsers(id?: string, name?: string, email?: string): Promise<User[]>;
+
+	/**
+	 * Creates a new user in the Headscale instance.
+	 *
+	 * @param username The username of the new user.
+	 * @param email Optional email of the new user.
+	 * @param displayName Optional display name of the new user.
+	 * @param pictureUrl Optional picture URL of the new user.
+	 * @returns A `User` object representing the newly created user.
+	 */
+	createUser(
+		username: string,
+		email?: string,
+		displayName?: string,
+		pictureUrl?: string,
+	): Promise<User>;
+
+	/**
+	 * Deletes a specific user by its ID.
+	 *
+	 * @param id The ID of the user to delete.
+	 */
+	deleteUser(id: string): Promise<void>;
+
+	/**
+	 * Renames a specific user by its ID.
+	 *
+	 * @param id The ID of the user to rename.
+	 * @param newName The new name for the user.
+	 */
+	renameUser(id: string, newName: string): Promise<void>;
+}
+
+export default defineApiEndpoints<UserEndpoints>((client, apiKey) => ({
+	getUsers: async (id, name, email) => {
+		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 client.apiFetch<{ users: User[] }>(
+			'GET',
+			'v1/user',
+			apiKey,
+			{ id, name, email },
+		);
+
+		return users;
+	},
+
+	createUser: async (username, email, displayName, pictureUrl) => {
+		const { user } = await client.apiFetch<{ user: User }>(
+			'POST',
+			'v1/user',
+			apiKey,
+			{ name: username, email, displayName, pictureUrl },
+		);
+
+		return user;
+	},
+
+	deleteUser: async (id) => {
+		await client.apiFetch<void>('DELETE', `v1/user/${id}`, apiKey);
+	},
+
+	renameUser: async (oldId, newName) => {
+		await client.apiFetch<void>(
+			'POST',
+			`v1/user/${oldId}/rename/${newName}`,
+			apiKey,
+		);
+	},
+}));

app/server/headscale/api/error-client.ts

@@ -0,0 +1,84 @@
+import type { HeadscaleConnectionError } from './error';
+
+/**
+ * Represents an error returned by the Headscale API.
+ */
+export interface HeadscaleAPIError {
+	requestUrl: `${string} ${string}`;
+	statusCode: number;
+	rawData: string;
+	data: Record<string, unknown> | null;
+}
+
+/**
+ * Type guard to check if an error is a HeadscaleAPIError.
+ * @param error - The error to check.
+ * @returns True if the error is a HeadscaleAPIError, false otherwise.
+ */
+export function isApiError(error: unknown): error is HeadscaleAPIError {
+	return (
+		error != null &&
+		typeof error === 'object' &&
+		'requestUrl' in error &&
+		'statusCode' in error &&
+		'rawData' in error &&
+		'data' in error
+	);
+}
+
+/**
+ * Type guard to check if an error is a HeadscaleConnectionError.
+ * @param error - The error to check.
+ * @returns True if the error is a HeadscaleConnectionError, false otherwise.
+ */
+export function isConnectionError(
+	error: unknown,
+): error is HeadscaleConnectionError {
+	return (
+		error != null &&
+		typeof error === 'object' &&
+		'requestUrl' in error &&
+		'errorCode' in error &&
+		'errorMessage' in error &&
+		'extraData' in error
+	);
+}
+
+/**
+ * Type guard to check if an error is a DataUnauthorizedError.
+ * This checks if the error has a `data` property with a `statusCode` of 401.
+ *
+ * @param error - The error to check.
+ * @returns True if the error is a DataUnauthorizedError, false otherwise.
+ */
+export function isDataUnauthorizedError(error: unknown): boolean {
+	return (
+		error != null &&
+		typeof error === 'object' &&
+		'data' in error &&
+		typeof error.data === 'object' &&
+		error.data != null &&
+		'statusCode' in error.data &&
+		error.data.statusCode === 401
+	);
+}
+
+/**
+ * Type guard to check if an error is a DataWithResponseInit wrapping a
+ * HeadscaleAPIError. This is used in loaders/actions to handle errors thrown by
+ * `data()` before they reach the ErrorBoundary.
+ *
+ * @param error - The error to check.
+ * @returns True if the error is a DataWithResponseInit containing a
+ * HeadscaleAPIError, false otherwise.
+ */
+export function isDataWithApiError(
+	error: unknown,
+): error is { data: HeadscaleAPIError } {
+	return (
+		error != null &&
+		typeof error === 'object' &&
+		'data' in error &&
+		isApiError(error.data)
+	);
+}

app/server/headscale/api/error.ts

@@ -0,0 +1,72 @@
+import { errors } from 'undici';
+
+/**
+ * Helper function that determines if an error is a Node.js exception
+ * @param - The error to check
+ * @returns True if the error is a Node.js exception, false otherwise
+ */
+function isNodeNetworkError(error: unknown): error is NodeJS.ErrnoException {
+	return (
+		error != null &&
+		typeof error === 'object' &&
+		'code' in error &&
+		'errno' in error
+	);
+}
+
+/**
+ * A friendly error representation for Headscale connection issues.
+ */
+export interface HeadscaleConnectionError {
+	requestUrl: string;
+	errorCode: string;
+	errorMessage: string;
+	extraData: Record<string, unknown> | null;
+}
+
+/**
+ * Convert an Undici error into a friendly HeadscaleAPIError.
+ * This is used to avoid exposing rough error edges to the user.
+ *
+ * @param error - The Undici error to convert.
+ * @param requestUrl - The URL of the request that caused the error.
+ * @returns A friendly HeadscaleAPIError.
+ */
+export function undiciToFriendlyError(
+	error: unknown,
+	requestUrl: string,
+): HeadscaleConnectionError {
+	// MARK: Do we need to go deeper into causes here?
+	if (error instanceof AggregateError) {
+		error = error.errors[0];
+	}
+
+	if (error instanceof errors.UndiciError) {
+		return {
+			requestUrl,
+			errorCode: error.code,
+			errorMessage: error.message,
+			extraData: null,
+		};
+	}
+
+	if (isNodeNetworkError(error)) {
+		return {
+			requestUrl,
+			errorCode: error.code ?? 'UNKNOWN_NODE_NETWORK_ERROR',
+			errorMessage: error.message,
+			extraData: {
+				syscall: error.syscall,
+				path: error.path,
+				errno: error.errno,
+			},
+		};
+	}
+
+	return {
+		requestUrl,
+		errorCode: 'UNKNOWN_ERROR',
+		errorMessage: 'An unknown error occured',
+		extraData: null,
+	};
+}

app/server/headscale/api/factory.ts

@@ -0,0 +1,45 @@
+import type { HeadscaleApiInterface } from '../api';
+
+/**
+ * Creates a strongly-typed group factory for a given endpoint interface.
+ *
+ * Example:
+ *   export const apiKeyGroup = defineGroup<ApiKeyEndpoints>({...})
+ */
+
+export interface EndpointFactory<T extends object> {
+	__type?: T;
+	(client: HeadscaleApiInterface['clientHelpers'], apiKey: string): T;
+}
+
+export function defineApiEndpoints<T extends object>(
+	factories: (
+		client: HeadscaleApiInterface['clientHelpers'],
+		apiKey: string,
+	) => T,
+): EndpointFactory<T> {
+	return factories;
+}
+
+export type ExtractApiEndpoints<F> = F extends EndpointFactory<infer T>
+	? T
+	: never;
+export type UnionToIntersection<U> = (
+	U extends any
+		? (k: U) => void
+		: never
+) extends (k: infer I) => void
+	? I
+	: never;
+
+/**
+ * Compose multiple endpoint sets into a single typed runtime client
+ */
+export function composeEndpoints<T extends readonly EndpointFactory<any>[]>(
+	factories: T,
+	clientHelpers: any,
+	apiKey: string,
+): UnionToIntersection<ExtractApiEndpoints<T[number]>> {
+	const instances = factories.map((f) => f(clientHelpers, apiKey));
+	return Object.assign({}, ...instances) as any;
+}

app/server/headscale/api/hasher.ts

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+import { dereference } from '@readme/openapi-parser';
+import { OpenAPIV2 } from 'openapi-types';
+
+/**
+ * A map of operation IDs to their hashes.
+ */
+export interface DocumentHash {
+	[operationId: string]: string;
+}
+
+/**
+ * Given an OpenAPI v2 document, generate a map of operations with hashes.
+ * This gives us deterministic identifers to determine the version of Headscale
+ * that is being used at runtime.
+ *
+ * @param doc The OpenAPI v2 document to hash.
+ * @returns A map of operation IDs to their hashes.
+ */
+export async function hashOpenApiDocument(
+	doc: OpenAPIV2.Document,
+): Promise<DocumentHash> {
+	const spec = await dereference(doc);
+	const hashes: DocumentHash = {};
+	const seen = new Set<string>();
+
+	for (const [path, item] of Object.entries(spec.paths)) {
+		for (const [method, operation] of Object.entries(item)) {
+			if (typeof operation !== 'object') {
+				continue;
+			}
+
+			const { parameters, responses } = operation as OpenAPIV2.OperationObject;
+			const raw = JSON.stringify(
+				{
+					path,
+					method: method.toUpperCase(),
+					parameters,
+					responses,
+				},
+				Object.keys({ path, method, parameters, responses }).sort(),
+			);
+
+			const hash = createHash('md5').update(raw).digest('hex').slice(0, 16);
+			const final = seen.has(hash) ? `${hash}_${seen.size}` : hash;
+			seen.add(final);
+			hashes[`${method.toUpperCase()} ${path}`] = final;
+		}
+	}
+
+	return hashes;
+}

app/server/headscale/api/index.ts

@@ -0,0 +1,340 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { dereference } from '@readme/openapi-parser';
+import type { OpenAPIV2 } from 'openapi-types';
+import { data } from 'react-router';
+import { Agent, type Dispatcher, request } from 'undici';
+import log from '~/utils/log';
+import endpointSets, { RuntimeApiClient } from './endpoints';
+import { undiciToFriendlyError } from './error';
+import { HeadscaleAPIError, isApiError } from './error-client';
+import { detectApiVersion, isAtLeast, type Version } from './version';
+
+/**
+ * A low-level composed interface for interacting with the Headscale API.
+ * This interface provides direct access to the underlying Undici agent
+ * and methods for making API requests.
+ *
+ * It is also responsible for handling OpenAPI spec polling and hashing to
+ * determine the implementations of API methods when requested for use.
+ */
+export interface HeadscaleApiInterface {
+	/**
+	 * The underlying Undici agent used for making requests.
+	 */
+	undiciAgent: Agent;
+
+	/**
+	 * The base URL of the Headscale API.
+	 */
+	baseUrl: string;
+
+	/**
+	 * The OpenAPI hashes retrieved from the Headscale instance at runtime.
+	 * This is used to determine which implementations of API methods to use.
+	 */
+	openapiHashes: Record<string, string> | null;
+
+	/**
+	 * The detected API version of the connected Headscale instance.
+	 */
+	apiVersion: Version;
+
+	/**
+	 * Retrieves a runtime API client for the given API key.
+	 *
+	 * @param apiKey The API key to use for authentication.
+	 * @returns A `RuntimeApiClient` instance for interacting with the API.
+	 */
+	getRuntimeClient(apiKey: string): RuntimeApiClient;
+
+	/**
+	 * A set of helper methods made available to API method implementations.
+	 * The idea is to make interacting with the API easier by providing
+	 * common functionality that can be reused across multiple methods.
+	 */
+	clientHelpers: {
+		/**
+		 * Checks if the connected Headscale instance's API version
+		 * is at least the specified version.
+		 *
+		 * @param version The version to check against.
+		 * @returns `true` if the API version is at least the specified version, `false` otherwise.
+		 */
+		isAtleast(version: Version): boolean;
+
+		/**
+		 * Makes a raw fetch request to the Headscale API via the Undici agent.
+		 * This method is used internally by API method implementations
+		 * to make requests to the Headscale API.
+		 *
+		 * @param path The API path to request.
+		 * @param options Optional request options.
+		 * @returns A promise that resolves to the response data.
+		 */
+		rawFetch(
+			path: string,
+			options?: Partial<Dispatcher.RequestOptions>,
+		): Promise<Dispatcher.ResponseData>;
+
+		/**
+		 * Makes a typed API fetch request to the Headscale API.
+		 * This method is used internally by API method implementations
+		 * to make requests to the Headscale API and parse the response.
+		 *
+		 * @param method The HTTP method to use.
+		 * @param apiPath The API path to request.
+		 * @param apiKey The API key to use for authentication.
+		 * @param bodyOrQuery Optional body or query parameters.
+		 * @returns A promise that resolves to the typed response data.
+		 */
+		apiFetch<T>(
+			method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+			apiPath: `v1/${string}`,
+			apiKey: string,
+			bodyOrQuery?: Record<string, unknown>,
+		): Promise<T>;
+	};
+}
+
+/**
+ * Creates a new Headscale API client interface.
+ *
+ * @param baseUrl The base URL of the Headscale API.
+ * @param certPath Optional path to a custom TLS certificate for secure connections.
+ * @returns A promise that resolves to a `HeadscaleApiClient` instance.
+ */
+export async function createHeadscaleInterface(
+	baseUrl: string,
+	certPath?: string,
+): Promise<HeadscaleApiInterface> {
+	const undiciAgent = await createUndiciAgent(certPath);
+	let openapiHashes: Record<string, string> | null = null;
+	let apiVersion: Version;
+
+	const rawFetch = async (
+		url: string,
+		options?: Partial<Dispatcher.RequestOptions>,
+	): Promise<Dispatcher.ResponseData> => {
+		const method = options?.method ?? 'GET';
+		log.debug('api', '%s %s', method, url);
+
+		try {
+			const res = await request(new URL(url, baseUrl), {
+				dispatcher: undiciAgent,
+				headers: {
+					...options?.headers,
+					Accept: 'application/json',
+					'User-Agent': `Headplane/${__VERSION__}`,
+				},
+
+				body: options?.body,
+				method,
+			});
+
+			return res;
+		} catch (error) {
+			const errorBody = undiciToFriendlyError(error, `${method} ${url}`);
+			throw data(errorBody, {
+				status: 502,
+				statusText: 'Bad Gateway',
+			});
+		}
+	};
+
+	const apiFetch = async <T>(
+		method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+		apiPath: `v1/${string}`,
+		apiKey: string,
+		bodyOrQuery?: Record<string, unknown>,
+	): Promise<T> => {
+		let url = `/api/${apiPath}`;
+		const options: Partial<Dispatcher.RequestOptions> = {
+			method: method,
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+			},
+		};
+
+		if (bodyOrQuery) {
+			if (method === 'GET' || method === 'DELETE') {
+				// Filter out undefined values
+
+				const params = new URLSearchParams();
+				for (const [key, value] of Object.entries(bodyOrQuery)) {
+					if (value !== undefined) {
+						params.append(key, String(value));
+					}
+				}
+
+				if ([...params.keys()].length > 0) {
+					url += `?${params.toString()}`;
+				}
+			} else {
+				options.body = JSON.stringify(bodyOrQuery);
+				options.headers = {
+					...options.headers,
+					'Content-Type': 'application/json',
+				};
+			}
+		}
+
+		const res = await rawFetch(url, options);
+		if (res.statusCode >= 400) {
+			log.debug(
+				'api',
+				'%s %s failed with status %d',
+				method,
+				apiPath,
+				res.statusCode,
+			);
+
+			const rawData = await res.body.text();
+			const jsonData = (() => {
+				try {
+					return JSON.parse(rawData) as Record<string, unknown>;
+				} catch {
+					return null;
+				}
+			})();
+
+			throw data(
+				{
+					requestUrl: `${method} ${apiPath}`,
+					statusCode: res.statusCode,
+					rawData,
+					data: jsonData,
+				} satisfies HeadscaleAPIError,
+				{
+					status: 502,
+					statusText: 'Bad Gateway',
+				},
+			);
+		}
+
+		return res.body.json() as Promise<T>;
+	};
+
+	/**
+	 * Polls the OpenAPI spec endpoint and generates operation hashes.
+	 * This is used to determine which implementations of API methods to use.
+	 *
+	 * @returns A promise that resolves to the OpenAPI operation hashes.
+	 */
+	async function fetchAndHashOpenapi(): Promise<Record<string, string> | null> {
+		try {
+			const res = await rawFetch('/swagger/v1/openapiv2.json');
+			if (res.statusCode !== 200) {
+				log.error('api', 'Failed to fetch OpenAPI spec: %d', res.statusCode);
+				return null;
+			}
+
+			const body = await res.body.json();
+			const spec = await dereference(body as OpenAPIV2.Document);
+			const hashes = generateSpecHashes(spec);
+			log.debug(
+				'api',
+				'OpenAPI hashes updated (%d endpoints)',
+				Object.keys(hashes).length,
+			);
+			return hashes;
+		} catch (error) {
+			if (isApiError(error)) {
+				log.debug('api', 'Failed to fetch OpenAPI spec: %d', error.statusCode);
+			}
+
+			return null;
+		}
+	}
+
+	const isAtleast = (version: Version): boolean => {
+		return isAtLeast(apiVersion, version);
+	};
+
+	openapiHashes = await fetchAndHashOpenapi();
+	apiVersion = detectApiVersion(openapiHashes);
+
+	setInterval(async () => {
+		const hashes = await fetchAndHashOpenapi();
+		if (hashes) {
+			openapiHashes = hashes;
+			apiVersion = detectApiVersion(openapiHashes);
+		}
+	}, 60_000); // every 60 seconds
+
+	return {
+		undiciAgent,
+		baseUrl,
+		openapiHashes,
+		apiVersion,
+		getRuntimeClient: (apiKey: string) =>
+			endpointSets(
+				{
+					rawFetch,
+					apiFetch,
+					isAtleast,
+				},
+				apiKey,
+			),
+		clientHelpers: {
+			rawFetch,
+			apiFetch,
+			isAtleast,
+		},
+	};
+}
+
+/**
+ * Creates a new Undici agent for making HTTP requests.
+ *
+ * @param certPath Optional path to a custom TLS certificate for secure connections.
+ * @returns A promise that resolves to an `Agent` instance.
+ */
+async function createUndiciAgent(certPath?: string): Promise<Agent> {
+	if (!certPath) {
+		return new Agent();
+	}
+
+	try {
+		log.debug('config', 'Loading certificate from %s', certPath);
+		const data = await readFile(certPath, 'utf8');
+
+		log.info('config', 'Using certificate from %s', certPath);
+		return new Agent({ connect: { ca: data.trim() } });
+	} catch (error) {
+		log.error('config', 'Failed to load Headscale TLS cert: %s', error);
+		log.debug('config', 'Error Details: %o', error);
+		return new Agent();
+	}
+}
+
+function generateSpecHashes(spec: OpenAPIV2.Document) {
+	const hashes: Record<string, string> = {};
+	const seen = new Set<string>();
+
+	for (const [path, item] of Object.entries(spec.paths)) {
+		for (const [method, operation] of Object.entries(item)) {
+			if (typeof operation !== 'object') {
+				continue;
+			}
+
+			const { parameters, responses } = operation as OpenAPIV2.OperationObject;
+			const raw = JSON.stringify(
+				{
+					path,
+					method: method.toUpperCase(),
+					parameters,
+					responses,
+				},
+				Object.keys({ path, method, parameters, responses }).sort(),
+			);
+
+			const hash = createHash('md5').update(raw).digest('hex').slice(0, 16);
+			const final = seen.has(hash) ? `${hash}_${seen.size}` : hash;
+			seen.add(final);
+			hashes[`${method.toUpperCase()} ${path}`] = final;
+		}
+	}
+
+	return hashes;
+}