test(auth): cover device code login

ndycode · ndycode · commit f047ee820c95 · 2026-03-22T21:11:23.000+08:00
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -76,8 +76,9 @@ The browser-based OAuth flow uses the same local callback port as Codex CLI: `ht
 If you are on SSH, WSL, or another environment where the browser callback flow is inconvenient:
 
 1. rerun `opencode auth login`
-2. choose `ChatGPT Plus/Pro (Manual URL Paste)`
-3. paste the full redirect URL after login completes in the browser
+2. choose `ChatGPT Plus/Pro MULTI (Device Code)`
+3. open the verification link, enter the one-time code, and wait for login to finish
+4. if device code is unavailable on your auth server, fall back to `ChatGPT Plus/Pro MULTI (Manual URL Paste)`
 
 ## Add the Plugin to OpenCode
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -182,8 +182,9 @@ Failed to access Codex API
 
 1. **Manual URL paste:**
    - Re-run `opencode auth login`
-   - Select **"ChatGPT Plus/Pro (Manual URL Paste)"**
-   - Paste the full redirect URL after login
+   - Select **"ChatGPT Plus/Pro MULTI (Device Code)"** first if you are on SSH, WSL, or a headless machine
+   - If device code is unavailable, fall back to **"ChatGPT Plus/Pro MULTI (Manual URL Paste)"**
+   - Paste the full redirect URL after login when using the manual flow
 
 2. **Check port 1455 availability:**
    ```bash
@@ -207,7 +208,7 @@ Failed to access Codex API
 **Solutions:**
 - Re-run `opencode auth login` to generate a fresh URL
 - Open the URL directly in browser (don't use a stale link)
-- For SSH/WSL/remote, use **"Manual URL Paste"** option
+- For SSH/WSL/remote, use **"Device Code"** first, then **"Manual URL Paste"** if needed
 
 </details>
 
@@ -617,7 +618,7 @@ ssh -L 1455:localhost:1455 user@remote
 
 **Docker / Containers:**
 - OAuth with localhost redirect doesn't work in containers
-- Use SSH port forwarding or manual URL flow
+- Use Device Code first, then SSH port forwarding or manual URL flow if needed
 
 </details>
 
diff --git a/test/device-code.test.ts b/test/device-code.test.ts
@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../lib/auth/auth.js", () => ({
+	AUTHORIZE_URL: "https://auth.openai.com/oauth/authorize",
+	CLIENT_ID: "test-client-id",
+	exchangeAuthorizationCode: vi.fn(async () => ({
+		type: "success" as const,
+		access: "device-access",
+		refresh: "device-refresh",
+		expires: Date.now() + 60_000,
+	})),
+}));
+
+vi.mock("../lib/logger.js", () => ({
+	logError: vi.fn(),
+}));
+
+import {
+	buildDeviceCodeInstructions,
+	completeDeviceCodeSession,
+	createDeviceCodeSession,
+} from "../lib/auth/device-code.js";
+import { exchangeAuthorizationCode } from "../lib/auth/auth.js";
+
+describe("device-code auth", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	it("creates a device-code session from the auth server response", async () => {
+		globalThis.fetch = vi.fn(async () =>
+			new Response(
+				JSON.stringify({
+					device_auth_id: "device-auth-1",
+					usercode: "ABCD-EFGH",
+					interval: "7",
+				}),
+				{ status: 200 },
+			),
+		) as typeof fetch;
+
+		const result = await createDeviceCodeSession();
+
+		expect(result).toEqual({
+			type: "ready",
+			session: {
+				verificationUrl: "https://auth.openai.com/codex/device",
+				userCode: "ABCD-EFGH",
+				deviceAuthId: "device-auth-1",
+				intervalSeconds: 7,
+			},
+		});
+		if (result.type === "ready") {
+			expect(buildDeviceCodeInstructions(result.session)).toContain("ABCD-EFGH");
+		}
+	});
+
+	it("reports when device-code login is unavailable", async () => {
+		globalThis.fetch = vi.fn(async () => new Response("missing", { status: 404 })) as typeof fetch;
+
+		const result = await createDeviceCodeSession();
+
+		expect(result.type).toBe("failed");
+		if (result.type === "failed") {
+			expect(result.failure.reason).toBe("http_error");
+			expect(result.failure.statusCode).toBe(404);
+			expect(result.failure.message).toContain("not enabled");
+		}
+	});
+
+	it("polls until an authorization code is issued and exchanges it", async () => {
+		globalThis.fetch = vi
+			.fn()
+			.mockResolvedValueOnce(new Response("", { status: 403 }))
+			.mockResolvedValueOnce(
+				new Response(
+					JSON.stringify({
+						authorization_code: "auth-code-1",
+						code_verifier: "code-verifier-1",
+					}),
+					{ status: 200 },
+				),
+			) as typeof fetch;
+
+		const result = await completeDeviceCodeSession({
+			verificationUrl: "https://auth.openai.com/codex/device",
+			userCode: "ABCD-EFGH",
+			deviceAuthId: "device-auth-1",
+			intervalSeconds: 0,
+		});
+
+		expect(result.type).toBe("success");
+		expect(vi.mocked(exchangeAuthorizationCode)).toHaveBeenCalledWith(
+			"auth-code-1",
+			"code-verifier-1",
+			"https://auth.openai.com/deviceauth/callback",
+		);
+	});
+
+	it("times out when no authorization code is issued", async () => {
+		globalThis.fetch = vi.fn(async () => new Response("", { status: 403 })) as typeof fetch;
+
+		const result = await completeDeviceCodeSession(
+			{
+				verificationUrl: "https://auth.openai.com/codex/device",
+				userCode: "ABCD-EFGH",
+				deviceAuthId: "device-auth-1",
+				intervalSeconds: 0,
+			},
+			{ maxWaitMs: 0 },
+		);
+
+		expect(result).toEqual({
+			type: "failed",
+			reason: "unknown",
+			message: "Device code authorization timed out after 15 minutes",
+		});
+	});
+});
diff --git a/test/index.test.ts b/test/index.test.ts
@@ -74,6 +74,29 @@ vi.mock("../lib/auth/server.js", () => ({
 	})),
 }));
 
+vi.mock("../lib/auth/device-code.js", () => ({
+	createDeviceCodeSession: vi.fn(async () => ({
+		type: "ready" as const,
+		session: {
+			verificationUrl: "https://auth.openai.com/codex/device",
+			userCode: "ABCD-EFGH",
+			deviceAuthId: "device-auth-1",
+			intervalSeconds: 1,
+		},
+	})),
+	buildDeviceCodeInstructions: vi.fn(
+		(session: { verificationUrl: string; userCode: string }) =>
+			`Open this link and sign in: ${session.verificationUrl}\nEnter this one-time code: ${session.userCode}\nThis code expires in about 15 minutes.`,
+	),
+	completeDeviceCodeSession: vi.fn(async () => ({
+		type: "success" as const,
+		access: "device-access-token",
+		refresh: "device-refresh-token",
+		expires: Date.now() + 3600_000,
+		idToken: "device-id-token",
+	})),
+}));
+
 vi.mock("../lib/cli.js", () => ({
 	promptLoginMode: vi.fn(async () => ({ mode: "add" })),
 	promptAddAnotherAccount: vi.fn(async () => false),
@@ -554,15 +577,16 @@ describe("OpenAIOAuthPlugin", () => {
 			expect(plugin.tool["codex-import"]).toBeDefined();
 		});
 
-		it("has two auth methods", () => {
-			expect(plugin.auth.methods).toHaveLength(2);
+		it("has three auth methods", () => {
+			expect(plugin.auth.methods).toHaveLength(3);
 			expect(plugin.auth.methods[0].label).toBe("ChatGPT Plus/Pro MULTI (Codex Subscription)");
-			expect(plugin.auth.methods[1].label).toBe("ChatGPT Plus/Pro MULTI (Manual URL Paste)");
+			expect(plugin.auth.methods[1].label).toBe("ChatGPT Plus/Pro MULTI (Device Code)");
+			expect(plugin.auth.methods[2].label).toBe("ChatGPT Plus/Pro MULTI (Manual URL Paste)");
 		});
 
 		it("rejects manual OAuth callbacks with mismatched state", async () => {
 			const authModule = await import("../lib/auth/auth.js");
-			const manualMethod = plugin.auth.methods[1] as unknown as {
+			const manualMethod = plugin.auth.methods[2] as unknown as {
 				authorize: () => Promise<{
 					validate: (input: string) => string | undefined;
 					callback: (input: string) => Promise<{ type: string; reason?: string; message?: string }>;
@@ -578,6 +602,56 @@ describe("OpenAIOAuthPlugin", () => {
 			expect(result.reason).toBe("invalid_response");
 			expect(vi.mocked(authModule.exchangeAuthorizationCode)).not.toHaveBeenCalled();
 		});
+
+		it("suggests device code when browser callback server is unavailable", async () => {
+			const serverModule = await import("../lib/auth/server.js");
+			vi.mocked(serverModule.startLocalOAuthServer).mockResolvedValueOnce({
+				ready: false,
+				close: vi.fn(),
+				waitForCode: vi.fn(async () => null),
+				port: 1455,
+			});
+
+			const autoMethod = plugin.auth.methods[0] as unknown as {
+				authorize: (inputs?: Record<string, string>) => Promise<{
+					instructions: string;
+					callback: () => Promise<{ type: string; message?: string }>;
+				}>;
+			};
+
+			const authResult = await autoMethod.authorize({ loginMode: "add", accountCount: "1" });
+			expect(authResult.instructions).toContain("Device Code");
+			expect(authResult.instructions).toContain("Manual URL Paste");
+
+			const result = await authResult.callback();
+			expect(result.type).toBe("failed");
+			expect(result.message).toContain("Device Code");
+		});
+
+		it("completes device code login and persists the account", async () => {
+			const deviceModule = await import("../lib/auth/device-code.js");
+			const deviceMethod = plugin.auth.methods[1] as unknown as {
+				authorize: () => Promise<{
+					instructions: string;
+					callback: () => Promise<{ type: string }>;
+				}>;
+			};
+
+			const authResult = await deviceMethod.authorize();
+			expect(authResult.instructions).toContain("ABCD-EFGH");
+			expect(authResult.instructions).toContain("https://auth.openai.com/codex/device");
+
+			const result = await authResult.callback();
+			expect(result.type).toBe("success");
+			expect(vi.mocked(deviceModule.createDeviceCodeSession)).toHaveBeenCalledTimes(1);
+			expect(vi.mocked(deviceModule.completeDeviceCodeSession)).toHaveBeenCalledTimes(1);
+			expect(mockStorage.accounts).toHaveLength(1);
+			expect(mockStorage.accounts[0]).toMatchObject({
+				refreshToken: "device-refresh-token",
+				accessToken: "device-access-token",
+				accountId: "acc-1",
+			});
+		});
 	});
 
 	describe("event handler", () => {
