Improve OAuth session expiry handling (#730)

- Improves the user experience when sessions expire by showing a "Log In" button
- Keeps deployment context after expiry so users don't have to re-enter the URL
- Adds automatic session recovery when tokens are updated from another window
- Adds OAuth scope validation to detect when required permissions change

Fixes #723

Author: EhabY

src/api/authInterceptor.ts

@@ -1,5 +1,6 @@
 import { type AxiosError, isAxiosError } from "axios";
 
+import { OAuthError } from "../oauth/errors";
 import { toSafeHost } from "../util";
 
 import type * as vscode from "vscode";
@@ -27,6 +28,7 @@ export type AuthRequiredHandler = (hostname: string) => Promise<boolean>;
  */
 export class AuthInterceptor implements vscode.Disposable {
 	private readonly interceptorId: number;
+	private authRequiredPromise: Promise<boolean> | null = null;
 
 	constructor(
 		private readonly client: CoderApi,
@@ -82,13 +84,21 @@ export class AuthInterceptor implements vscode.Disposable {
 				this.logger.debug("Token refresh successful, retrying request");
 				return this.retryRequest(error, newTokens.access_token);
 			} catch (refreshError) {
-				this.logger.error("OAuth refresh failed:", refreshError);
+				if (refreshError instanceof OAuthError) {
+					const msg = `Token refresh failed: ${refreshError.message}`;
+					if (refreshError.requiresReAuth) {
+						this.logger.warn(msg);
+					} else {
+						this.logger.error(msg);
+					}
+				} else {
+					this.logger.error("Token refresh failed:", refreshError);
+				}
 			}
 		}
 
 		if (this.onAuthRequired) {
-			this.logger.debug("Triggering interactive re-authentication");
-			const success = await this.onAuthRequired(hostname);
+			const success = await this.executeAuthRequired(hostname);
 			if (success) {
 				const auth = await this.secretsManager.getSessionAuth(hostname);
 				if (auth) {
@@ -101,6 +111,28 @@ export class AuthInterceptor implements vscode.Disposable {
 		throw error;
 	}
 
+	/**
+	 * Execute auth required callback with deduplication.
+	 * Multiple concurrent 401s will share the same promise.
+	 */
+	private async executeAuthRequired(hostname: string): Promise<boolean> {
+		if (this.authRequiredPromise) {
+			this.logger.debug(
+				"Auth callback already in progress, waiting for result",
+			);
+			return this.authRequiredPromise;
+		}
+
+		this.logger.debug("Triggering re-authentication");
+		this.authRequiredPromise = this.onAuthRequired!(hostname);
+
+		try {
+			return await this.authRequiredPromise;
+		} finally {
+			this.authRequiredPromise = null;
+		}
+	}
+
 	private retryRequest(error: AxiosError, token: string): Promise<unknown> {
 		if (!error.config) {
 			throw error;

src/commands.ts

@@ -209,12 +209,12 @@ export class Commands {
 
 		await this.deploymentManager.clearDeployment();
 
-		void vscode.window
+		vscode.window
 			.showInformationMessage("You've been logged out of Coder!", "Login")
 			.then((action) => {
 				if (action === "Login") {
 					this.login().catch((error) => {
-						this.logger.error("Failed to login", error);
+						this.logger.error("Login failed", error);
 					});
 				}
 			});

src/core/secretsManager.ts

@@ -38,7 +38,7 @@ export type CurrentDeploymentState = z.infer<
  */
 const OAuthTokenDataSchema = z.object({
 	refresh_token: z.string().optional(),
-	scope: z.string().optional(),
+	scope: z.string(),
 	expiry_timestamp: z.number(),
 });
 

src/deployment/deploymentManager.ts

@@ -12,11 +12,6 @@ import { type Deployment, type DeploymentWithAuth } from "./types";
 import type { User } from "coder/site/src/api/typesGenerated";
 import type * as vscode from "vscode";
 
-/**
- * Internal state type that allows mutation of user property.
- */
-type DeploymentWithUser = Deployment & { user: User };
-
 /**
  * Manages deployment state for the extension.
  *
@@ -35,7 +30,7 @@ export class DeploymentManager implements vscode.Disposable {
 	private readonly contextManager: ContextManager;
 	private readonly logger: Logger;
 
-	#deployment: DeploymentWithUser | null = null;
+	#deployment: Deployment | null = null;
 	#authListenerDisposable: vscode.Disposable | undefined;
 	#crossWindowSyncDisposable: vscode.Disposable | undefined;
 
@@ -78,7 +73,7 @@ export class DeploymentManager implements vscode.Disposable {
 	 * Check if we have an authenticated deployment (does not guarantee that the current auth data is valid).
 	 */
 	public isAuthenticated(): boolean {
-		return this.#deployment !== null;
+		return this.contextManager.get("coder.authenticated");
 	}
 
 	/**
@@ -89,10 +84,10 @@ export class DeploymentManager implements vscode.Disposable {
 	public async setDeploymentIfValid(
 		deployment: Deployment & { token?: string },
 	): Promise<boolean> {
-		const auth = await this.secretsManager.getSessionAuth(
-			deployment.safeHostname,
-		);
-		const token = deployment.token ?? auth?.token;
+		const token =
+			deployment.token ??
+			(await this.secretsManager.getSessionAuth(deployment.safeHostname))
+				?.token;
 		const tempClient = CoderApi.create(deployment.url, token, this.logger);
 
 		try {
@@ -132,7 +127,8 @@ export class DeploymentManager implements vscode.Disposable {
 		// Register auth listener before setDeployment so background token refresh
 		// can update client credentials via the listener
 		this.registerAuthListener();
-		this.updateAuthContexts();
+		// Contexts must be set before refresh (providers check isAuthenticated)
+		this.updateAuthContexts(deployment.user);
 		this.refreshWorkspaces();
 
 		await this.oauthSessionManager.setDeployment(deployment);
@@ -143,16 +139,32 @@ export class DeploymentManager implements vscode.Disposable {
 	 * Clears the current deployment.
 	 */
 	public async clearDeployment(): Promise<void> {
+		this.suspendSession();
 		this.#authListenerDisposable?.dispose();
 		this.#authListenerDisposable = undefined;
 		this.#deployment = null;
 
-		this.client.setCredentials(undefined, undefined);
+		await this.secretsManager.setCurrentDeployment(undefined);
+	}
+
+	/**
+	 * Suspend session: shows logged-out state but keeps deployment for easy re-login.
+	 * Auth listener remains active so recovery can happen automatically if tokens update.
+	 */
+	public suspendSession(): void {
 		this.oauthSessionManager.clearDeployment();
-		this.updateAuthContexts();
-		this.refreshWorkspaces();
+		this.client.setCredentials(undefined, undefined);
+		this.updateAuthContexts(undefined);
+		this.clearWorkspaces();
+	}
 
-		await this.secretsManager.setCurrentDeployment(undefined);
+	/**
+	 * Clear all workspace providers without fetching.
+	 */
+	private clearWorkspaces(): void {
+		for (const provider of this.workspaceProviders) {
+			provider.clear();
+		}
 	}
 
 	public dispose(): void {
@@ -163,6 +175,7 @@ export class DeploymentManager implements vscode.Disposable {
 	/**
 	 * Register auth listener for the current deployment.
 	 * Updates credentials when they change (token refresh, cross-window sync).
+	 * Also handles recovery from suspended session state.
 	 */
 	private registerAuthListener(): void {
 		if (!this.#deployment) {
@@ -182,7 +195,18 @@ export class DeploymentManager implements vscode.Disposable {
 				}
 
 				if (auth) {
-					this.client.setCredentials(auth.url, auth.token);
+					if (this.isAuthenticated()) {
+						this.client.setCredentials(auth.url, auth.token);
+					} else {
+						this.logger.debug(
+							"Token updated after session suspended, recovering",
+						);
+						await this.setDeploymentIfValid({
+							url: auth.url,
+							safeHostname,
+							token: auth.token,
+						});
+					}
 				} else {
 					await this.clearDeployment();
 				}
@@ -210,8 +234,7 @@ export class DeploymentManager implements vscode.Disposable {
 	/**
 	 * Update authentication-related contexts.
 	 */
-	private updateAuthContexts(): void {
-		const user = this.#deployment?.user;
+	private updateAuthContexts(user: User | undefined): void {
 		this.contextManager.set("coder.authenticated", Boolean(user));
 		const isOwner = user?.roles.some((r) => r.name === "owner") ?? false;
 		this.contextManager.set("coder.isOwner", isOwner);

src/extension.ts

@@ -70,10 +70,33 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 
 	const deployment = await secretsManager.getCurrentDeployment();
 
-	// Create OAuth session manager with login coordinator
+	// Shared handler for auth failures (used by interceptor + session manager)
+	const handleAuthFailure = (): Promise<void> => {
+		deploymentManager.suspendSession();
+		vscode.window
+			.showWarningMessage(
+				"Session expired. You have been signed out.",
+				"Log In",
+			)
+			.then(async (action) => {
+				if (action === "Log In") {
+					try {
+						await commands.login({
+							url: deploymentManager.getCurrentDeployment()?.url,
+						});
+					} catch (err) {
+						output.error("Login failed", err);
+					}
+				}
+			});
+		return Promise.resolve();
+	};
+
+	// Create OAuth session manager - callback handles background refresh failures
 	const oauthSessionManager = OAuthSessionManager.create(
 		deployment,
 		serviceContainer,
+		handleAuthFailure,
 	);
 	ctx.subscriptions.push(oauthSessionManager);
 
@@ -94,19 +117,20 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 		output,
 		oauthSessionManager,
 		secretsManager,
-		() => {
-			void vscode.window.showWarningMessage(
-				"Session expired. Please log in again using the Coder sidebar.",
-			);
-			return Promise.resolve(false);
+		async () => {
+			await handleAuthFailure();
+			return false;
 		},
 	);
 	ctx.subscriptions.push(authInterceptor);
 
+	const isAuthenticated = () => contextManager.get("coder.authenticated");
+
 	const myWorkspacesProvider = new WorkspaceProvider(
 		WorkspaceQuery.Mine,
 		client,
 		output,
+		isAuthenticated,
 		5,
 	);
 	ctx.subscriptions.push(myWorkspacesProvider);
@@ -115,6 +139,7 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 		WorkspaceQuery.All,
 		client,
 		output,
+		isAuthenticated,
 	);
 	ctx.subscriptions.push(allWorkspacesProvider);
 
@@ -295,11 +320,10 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 		output.info(`Initializing deployment: ${deployment.url}`);
 		deploymentManager
 			.setDeploymentIfValid(deployment)
+			// Failure is logged internally
 			.then((success) => {
 				if (success) {
 					output.info("Deployment authenticated and set");
-				} else {
-					output.info("Failed to authenticate, deployment not set");
 				}
 			})
 			.catch((error: unknown) => {
@@ -324,7 +348,7 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
 				process.env.CODER_URL?.trim();
 			if (defaultUrl) {
 				commands.login({ url: defaultUrl, autoLogin: true }).catch((error) => {
-					output.error("Failed to auto-login", error);
+					output.error("Auto-login failed", error);
 				});
 			}
 		}

src/oauth/authorizer.ts

@@ -8,6 +8,7 @@ import { type Logger } from "../logging/logger";
 
 import {
 	AUTH_GRANT_TYPE,
+	DEFAULT_OAUTH_SCOPES,
 	PKCE_CHALLENGE_METHOD,
 	RESPONSE_TYPE,
 	TOKEN_ENDPOINT_AUTH_METHOD,
@@ -29,19 +30,6 @@ import type {
 	User,
 } from "coder/site/src/api/typesGenerated";
 
-/**
- * Minimal scopes required by the VS Code extension.
- */
-const DEFAULT_OAUTH_SCOPES = [
-	"workspace:read",
-	"workspace:update",
-	"workspace:start",
-	"workspace:ssh",
-	"workspace:application_connect",
-	"template:read",
-	"user:read_personal",
-].join(" ");
-
 /**
  * Handles the OAuth authorization code flow for authenticating with Coder deployments.
  * Encapsulates client registration, PKCE challenge, and token exchange.

src/oauth/constants.ts

@@ -2,6 +2,17 @@
 export const AUTH_GRANT_TYPE = "authorization_code";
 export const REFRESH_GRANT_TYPE = "refresh_token";
 
+// Minimal scopes required by the VS Code extension
+export const DEFAULT_OAUTH_SCOPES = [
+	"workspace:read",
+	"workspace:update",
+	"workspace:start",
+	"workspace:ssh",
+	"workspace:application_connect",
+	"template:read",
+	"user:read_personal",
+].join(" ");
+
 // OAuth 2.1 Response Types
 export const RESPONSE_TYPE = "code";
 

src/oauth/errors.ts

@@ -34,6 +34,15 @@ export class OAuthError extends Error {
 		);
 		this.name = "OAuthError";
 	}
+
+	/**
+	 * Returns true if this error indicates the user needs to re-authenticate.
+	 */
+	get requiresReAuth(): boolean {
+		return (
+			this.errorCode === "invalid_grant" || this.errorCode === "invalid_client"
+		);
+	}
 }
 
 export function parseOAuthError(error: unknown): OAuthError | null {
@@ -57,9 +66,3 @@ function isOAuth2Error(data: unknown): data is OAuth2Error {
 		typeof data.error === "string"
 	);
 }
-
-export function requiresReAuthentication(error: OAuthError): boolean {
-	return (
-		error.errorCode === "invalid_grant" || error.errorCode === "invalid_client"
-	);
-}

src/oauth/metadataClient.ts

@@ -18,7 +18,7 @@ import type { Logger } from "../logging/logger";
 
 const OAUTH_DISCOVERY_ENDPOINT = "/.well-known/oauth-authorization-server";
 
-const REQUIRED_GRANT_TYPES: readonly string[] = [
+const REQUIRED_GRANT_TYPES: readonly OAuth2ProviderGrantType[] = [
 	AUTH_GRANT_TYPE,
 	REFRESH_GRANT_TYPE,
 ];