feat: add a warning banner on the login page for misconfigured cookies

CHANGELOG.md

@@ -2,6 +2,7 @@
 - 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.
 
 ---
 

app/routes/auth/login/page.tsx

@@ -1,40 +1,35 @@
-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 Logout from './logout';
 
-export async function loader({
+export async function loader({ request, context }: Route.LoaderArgs) {
-	request,
-	context,
-}: LoaderFunctionArgs<LoadContext>) {
 	try {
 		await context.sessions.auth(request);
 		return redirect('/machines');
 	} catch {}
 
 	const qp = new URL(request.url).searchParams;
-	const state = qp.get('s') ?? undefined;
+	const urlState = 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) {
+	if (urlState !== 'logout' && ssoOnly) {
 		// This shouldn't be possible, but still a safe sanity check
 		if (!context.oidc) {
 			throw data(
@@ -49,30 +44,35 @@ export async function loader({
 	}
 
 	return {
-		oidc: context.oidc,
+		isOidcEnabled: context.oidc !== undefined,
-		state,
+		isCookieSecureEnabled: context.config.server.cookie_secure,
+		urlState,
 	};
 }
 
-export async function action(request: ActionFunctionArgs<LoadContext>) {
+export async function action(request: Route.ActionArgs) {
 	return loginAction(request);
 }
 
-export default function Page() {
+export default function Page({ loaderData, actionData }: Route.ComponentProps) {
-	const { state, oidc } = useLoaderData<typeof loader>();
+	const { isOidcEnabled, isCookieSecureEnabled, urlState } = loaderData;
-	const formData = useActionData<typeof action>();
+	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,71 @@ 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">
+			<div>
-				<Card.Title>Welcome to Headplane</Card.Title>
+				{showCookieWarning ? (
-				<Form method="POST">
+					<Card className="max-w-md m-4 sm:m-0 mb-4 sm:mb-4 border border-red-500">
-					<Card.Text>
+						<div className="flex items-center justify-between gap-4">
-						Enter an API key to authenticate with Headplane. You can generate
+							<Card.Title className="text-red-500">
-						one by running <Code>headscale apikeys create</Code> in your
+								Configuration Issue
-						terminal.
+							</Card.Title>
-					</Card.Text>
+							<AlertCircle className="w-6 h-6 mb-2 text-red-500" />
-					<Input
+						</div>
-						className="mt-8 mb-2"
+						<Card.Text className="text-sm text-red-600 dark:text-red-400">
-						isRequired
+							Headplane is configured to use secure cookies, but this site is
-						label="API Key"
+							being served over an insecure connection and login will not work
-						labelHidden
+							correctly.{' '}
-						name="api_key"
+							<Link
-						placeholder="API Key"
+								name="Headplane Common Issues"
-						type="password"
+								to="https://headplane.net/configuration/common-issues#issue-logging-in-does-not-do-anything"
-					/>
+							>
-					{formData?.success === false ? (
+								Learn more.
-						<Card.Text className="text-sm mb-2 text-red-600 dark:text-red-300">
+							</Link>
-							{formData.message}
 						</Card.Text>
-					) : undefined}
+					</Card>
-					<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>
 				) : 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>
+					{isOidcEnabled ? (
+						<RemixLink to="/oidc/start">
+							<Button className="w-full mt-2" variant="light">
+								Single Sign-On
+							</Button>
+						</RemixLink>
+					) : undefined}
+				</Card>
+			</div>
 		</div>
 	);
 }

app/server/index.ts

@@ -40,6 +40,12 @@ const agents = await createHeadplaneAgent(
 // These are usually per-request things that we need access to, like the
 // helper that can issue and revoke cookies.
 export type LoadContext = typeof appLoadContext;
+
+import 'react-router';
+declare module 'react-router' {
+	interface AppLoadContext extends LoadContext {}
+}
+
 const appLoadContext = {
 	config,
 	hs: await loadHeadscaleConfig(

docs/.vitepress/config.ts

@@ -25,7 +25,13 @@ export default defineConfig({
 							{ text: 'Docker', link: '/install/docker' },
 						],
 					},
-					{ text: 'Configuration', link: '/configuration' },
+					{
+						text: 'Configuration',
+						link: '/configuration',
+						items: [
+							{ text: 'Common Issues', link: '/configuration/common-issues' },
+						],
+					},
 					{ text: 'Nix', link: '/Nix' },
 					{ text: 'NixOS', link: '/NixOS-options' },
 					{

docs/configuration/common-issues.md

@@ -0,0 +1,25 @@
+---
+title: Common Issues
+description: Common issues and their solutions
+---
+
+# Common Issues and Their Solutions
+This document outlines some common issues users may encounter while using Headplane, along with their solutions.
+
+## Login does not work
+::: tip
+Headplane tries to detect misconfigurations and will surface a warning banner on
+the login page if it detects any abnormalities. You may see a banner like this:
+<figure>
+    <img class="dark-only" src="../assets/login-banner-dark.png" />
+    <img class="light-only" src="../assets/login-banner-light.png" />
+    <figcaption>Login Warning Banner</figcaption>
+</figure>
+:::
+
+If you attempt to log in to Headplane but nothing happens, it may be due to a
+misconfiguration of the server cookie settings. In your Headplane configuration,
+ensure that `server.cookie_secure` is set appropriately based on how you are
+accessing Headplane:
+- Serving over HTTPS: `cookie_secure` should be enabled (`true`).
+- Serving over HTTP: `cookie_secure` should be disabled (`false`).

tsconfig.json

@@ -1,32 +1,26 @@
 {
 	"include": [
-		"**/*.ts",
+		"**/*",
-		"**/*.tsx",
+		"**/.server/**/*",
-		"**/.server/**/*.ts",
+		"**/.client/**/*",
-		"**/.server/**/*.tsx",
+		".react-router/types/**/*"
-		"**/.client/**/*.ts",
-		"**/.client/**/*.tsx"
 	],
 	"compilerOptions": {
 		"lib": ["DOM", "DOM.Iterable", "ES2022"],
-		"types": ["vite/client"],
+		"types": ["node", "vite/client"],
-		"isolatedModules": true,
-		"esModuleInterop": true,
-		"jsx": "react-jsx",
-		"module": "ESNext",
-		"moduleResolution": "Bundler",
-		"resolveJsonModule": true,
 		"target": "ES2022",
-		"strict": true,
+		"module": "ESNext",
-		"allowJs": true,
+		"moduleResolution": "bundler",
-		"skipLibCheck": true,
+		"jsx": "react-jsx",
-		"forceConsistentCasingInFileNames": true,
+		"rootDirs": [".", "./.react-router/types"],
 		"paths": {
-			"~/*": ["./app/*"],
+			"~/*": ["./app/*"]
-			"~server/*": ["./server/*"]
 		},
-
+		"esModuleInterop": true,
-		// Vite takes care of building everything, not tsc.
+		"verbatimModuleSyntax": false,
-		"noEmit": true
+		"noEmit": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"strict": true
 	}
 }