feat: improve oauth login inputs and callback UX (#31)

Author: gnapse

README.md

@@ -26,17 +26,26 @@ npm link
 
 ```sh
 ol auth login     # opens browser for OAuth authorization
+ol auth login --base-url <your-outline-url> # skip base URL prompt for this login
+ol auth login --client-id <your-client-id>  # skip prompt for this login
+ol auth login --callback-port 54969         # override local callback port
 ol auth status    # show current auth state
 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`
+   (for self-hosted instances or non-default URLs)
+5. If needed, pass `--callback-port <port>` or set `OUTLINE_OAUTH_CALLBACK_PORT`
+   and register `http://localhost:<port>/callback` in your OAuth app
 
-The client ID is saved for future logins. You can also set `OUTLINE_OAUTH_CLIENT_ID` env var.
+The client ID is saved for future logins. You can also set `OUTLINE_OAUTH_CLIENT_ID`
+for your local environment.
 
 ### Manual token login
 
@@ -54,7 +63,10 @@ Token resolution: `OUTLINE_API_TOKEN` env var → `~/.config/outline-cli/config.
 
 Base URL resolution: `OUTLINE_URL` env var → config file → `https://app.getoutline.com`.
 
-Self-hosted instances: provide your instance URL during `ol auth login` or set `OUTLINE_URL`.
+Callback port resolution for OAuth login:
+`--callback-port` → `OUTLINE_OAUTH_CALLBACK_PORT` → `54969`.
+
+Self-hosted instances: pass `--base-url` or set `OUTLINE_URL` (you can still provide it interactively).
 
 ## Commands
 

src/__tests__/oauth-server.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { startOAuthCallbackServer } from "../lib/oauth-server.js";
+
+describe("oauth callback server", () => {
+	it("returns success page and resolves authorization code", async () => {
+		const callbackServer = await startOAuthCallbackServer({
+			state: "expected-state",
+			timeoutMs: 10_000,
+			port: 0,
+		});
+
+		const response = await fetch(
+			`${callbackServer.redirectUri}?code=test-code&state=expected-state`,
+		);
+		const html = await response.text();
+
+		expect(response.status).toBe(200);
+		expect(html).toContain("Login complete");
+		await expect(callbackServer.waitForCode).resolves.toBe("test-code");
+	});
+
+	it("returns error page and rejects on state mismatch", async () => {
+		const callbackServer = await startOAuthCallbackServer({
+			state: "expected-state",
+			timeoutMs: 10_000,
+			port: 0,
+		});
+		const rejection = callbackServer.waitForCode.then(
+			() => new Error("Expected OAuth state mismatch."),
+			(error) => error as Error,
+		);
+
+		const response = await fetch(
+			`${callbackServer.redirectUri}?code=test-code&state=wrong-state`,
+		);
+		const html = await response.text();
+
+		expect(response.status).toBe(400);
+		expect(html).toContain("Authentication failed");
+		const error = await rejection;
+		expect(error.message).toBe("OAuth state mismatch.");
+	});
+
+	it("returns error page and rejects when OAuth provider sends an error", async () => {
+		const callbackServer = await startOAuthCallbackServer({
+			state: "expected-state",
+			timeoutMs: 10_000,
+			port: 0,
+		});
+		const rejection = callbackServer.waitForCode.then(
+			() => new Error("Expected OAuth provider error."),
+			(error) => error as Error,
+		);
+
+		const response = await fetch(
+			`${callbackServer.redirectUri}?error=access_denied&error_description=User%20denied`,
+		);
+		const html = await response.text();
+
+		expect(response.status).toBe(400);
+		expect(html).toContain("Authentication failed");
+		const error = await rejection;
+		expect(error.message).toBe("OAuth authorization denied: User denied");
+	});
+});