feat: use fixed oauth callback URL

Author: gnapse

README.md

@@ -35,7 +35,7 @@ ol auth logout    # clear saved credentials
 **Setup:**
 
 1. Create a public OAuth app in Outline (Settings → Applications)
-2. Set the redirect URI to `http://localhost` (any port is fine)
+2. Set the redirect URI to `http://localhost:54969/callback`
 3. Run `ol auth login` and enter your OAuth client ID when prompted
    (or pass it directly with `--client-id <your-client-id>`)
 4. If needed, pass `--base-url <your-outline-url>` or set `OUTLINE_URL`

src/__tests__/oauth-server.test.ts

@@ -6,6 +6,7 @@ describe("oauth callback server", () => {
 		const callbackServer = await startOAuthCallbackServer({
 			state: "expected-state",
 			timeoutMs: 10_000,
+			port: 0,
 		});
 
 		const response = await fetch(
@@ -22,6 +23,7 @@ describe("oauth callback server", () => {
 		const callbackServer = await startOAuthCallbackServer({
 			state: "expected-state",
 			timeoutMs: 10_000,
+			port: 0,
 		});
 		const rejection = callbackServer.waitForCode.then(
 			() => new Error("Expected OAuth state mismatch."),
@@ -43,6 +45,7 @@ describe("oauth callback server", () => {
 		const callbackServer = await startOAuthCallbackServer({
 			state: "expected-state",
 			timeoutMs: 10_000,
+			port: 0,
 		});
 		const rejection = callbackServer.waitForCode.then(
 			() => new Error("Expected OAuth provider error."),

src/commands/auth.ts

@@ -11,7 +11,10 @@ import {
 	saveConfig,
 } from "../lib/auth.js";
 import { buildAuthorizationUrl, exchangeCodeForToken } from "../lib/oauth.js";
-import { startOAuthCallbackServer } from "../lib/oauth-server.js";
+import {
+	DEFAULT_OAUTH_CALLBACK_PORT,
+	startOAuthCallbackServer,
+} from "../lib/oauth-server.js";
 import { formatError } from "../lib/output.js";
 import {
 	generateCodeChallenge,
@@ -117,7 +120,32 @@ export function registerAuthCommand(program: Command): void {
 				const codeChallenge = generateCodeChallenge(codeVerifier);
 				const state = generateState();
 
-				const callbackServer = await startOAuthCallbackServer({ state });
+				let callbackServer: Awaited<
+					ReturnType<typeof startOAuthCallbackServer>
+				>;
+				try {
+					callbackServer = await startOAuthCallbackServer({ state });
+				} catch (err) {
+					const error = err as NodeJS.ErrnoException;
+					const hints = [
+						`Ensure http://localhost:${DEFAULT_OAUTH_CALLBACK_PORT}/callback is reachable from your browser`,
+						"Re-run with 'ol auth login --token <token>' for manual auth",
+					];
+					if (error.code === "EADDRINUSE") {
+						hints.unshift(
+							`Port ${DEFAULT_OAUTH_CALLBACK_PORT} is already in use. Close the other process using it.`,
+						);
+					}
+
+					console.error(
+						formatError(
+							"OAUTH_CALLBACK_SERVER_FAILED",
+							`Could not start local OAuth callback server: ${error.message}`,
+							hints,
+						),
+					);
+					process.exit(1);
+				}
 				const authorizationUrl = buildAuthorizationUrl({
 					baseUrl: url,
 					clientId,

src/lib/oauth-server.ts

@@ -4,6 +4,7 @@ import type { AddressInfo } from "node:net";
 interface OAuthServerOptions {
 	state: string;
 	timeoutMs?: number;
+	port?: number;
 }
 
 export interface OAuthCallbackServer {
@@ -13,6 +14,8 @@ export interface OAuthCallbackServer {
 	close: () => void;
 }
 
+export const DEFAULT_OAUTH_CALLBACK_PORT = 54969;
+
 function escapeHtml(text: string): string {
 	return text
 		.replaceAll("&", "&")
@@ -128,7 +131,11 @@ function renderErrorPage(message: string): string {
 export async function startOAuthCallbackServer(
 	options: OAuthServerOptions,
 ): Promise<OAuthCallbackServer> {
-	const { state, timeoutMs = 3 * 60 * 1000 } = options;
+	const {
+		state,
+		timeoutMs = 3 * 60 * 1000,
+		port = DEFAULT_OAUTH_CALLBACK_PORT,
+	} = options;
 	let origin = "http://localhost";
 	let resolved = false;
 	let resolveCode: (code: string) => void;
@@ -202,12 +209,23 @@ export async function startOAuthCallbackServer(
 		rejectCode(err as Error);
 	});
 
-	await new Promise<void>((resolve) => {
-		server.listen(0, "127.0.0.1", resolve);
+	await new Promise<void>((resolve, reject) => {
+		const onListening = () => {
+			server.off("error", onError);
+			resolve();
+		};
+		const onError = (err: Error) => {
+			server.off("listening", onListening);
+			reject(err);
+		};
+
+		server.once("listening", onListening);
+		server.once("error", onError);
+		server.listen(port, "127.0.0.1");
 	});
 
-	const { port } = server.address() as AddressInfo;
-	origin = `http://localhost:${port}`;
+	const { port: listeningPort } = server.address() as AddressInfo;
+	origin = `http://localhost:${listeningPort}`;
 	const redirectUri = `${origin}/callback`;
 
 	const timeout = setTimeout(() => {
@@ -233,5 +251,5 @@ export async function startOAuthCallbackServer(
 		},
 	);
 
-	return { port, redirectUri, waitForCode, close };
+	return { port: listeningPort, redirectUri, waitForCode, close };
 }