fix: recover mTLS auth after settings races (#976)

A session suspended by an mTLS or coder.headerCommand failure stayed
suspended even after the user fixed the setting. Two races caused it:
a request could 401 from a mid-flight settings change with no way to
recover, and nothing re-tried once the fix landed.

- Suspended sessions auto-recover once auth settings become valid
  again, with no logout/login round-trip.
- A 401 caused by a settings change mid-flight is retried silently
  under the new settings instead of escalating to an interactive
  prompt.
- Retried requests no longer carry stale headers from a previous
  header-command run.
- Logout, deployment switch, or dispose during an in-flight auth
  verify is no longer overwritten by the verify finishing.
- Cross-window login keeps listening if the first observed token from
  another window is invalid, so a follow-up valid write still resolves
  the dialog.
- Config-change side-effects (reload prompt, recovery, reconnects)
  fire once edits settle instead of on the first event of a burst.
- Concurrent logout no longer leaves stale deployment data in storage.

Closes #973

Author: EhabY

src/api/authInterceptor.ts

@@ -9,7 +9,6 @@ import type * as vscode from "vscode";
 import type { ServiceContainer } from "../core/container";
 import type { SecretsManager } from "../core/secretsManager";
 import type { Logger } from "../logging/logger";
-import type { RequestConfigWithMeta } from "../logging/types";
 import type { OAuthSessionManager } from "../oauth/sessionManager";
 
 import type { CoderApi } from "./coderApi";
@@ -58,13 +57,6 @@ export class AuthInterceptor implements vscode.Disposable {
 			throw error;
 		}
 
-		if (error.config) {
-			const config = error.config as { _retryAttempted?: boolean };
-			if (config._retryAttempted) {
-				throw error;
-			}
-		}
-
 		if (error.response?.status !== 401) {
 			throw error;
 		}
@@ -82,6 +74,26 @@ export class AuthInterceptor implements vscode.Disposable {
 		error: AxiosError,
 		hostname: string,
 	): Promise<unknown> {
+		const config = error.config;
+
+		// Checked before _retryAttempted so an OAuth-retry 401 caused by a
+		// fresh settings change still gets one silent attempt.
+		if (
+			config &&
+			!config._authConfigRetryAttempted &&
+			this.client.hasAuthConfigChangedSince(config.authConfigVersion)
+		) {
+			config._authConfigRetryAttempted = true;
+			this.logger.debug(
+				"Authentication settings changed during request, retrying once",
+			);
+			return this.client.getAxiosInstance().request(config);
+		}
+
+		if (config?._retryAttempted) {
+			throw error;
+		}
+
 		this.logger.debug("Received 401 response, attempting recovery");
 		return this.authTelemetry.traceAuthRecovery(async (recorder) => {
 			recorder.logReceived();
@@ -166,12 +178,9 @@ export class AuthInterceptor implements vscode.Disposable {
 			throw error;
 		}
 
-		const config = error.config as RequestConfigWithMeta & {
-			_retryAttempted?: boolean;
-		};
-		config._retryAttempted = true;
-		config.headers[coderSessionTokenHeader] = token;
-		return this.client.getAxiosInstance().request(config);
+		error.config._retryAttempted = true;
+		error.config.headers[coderSessionTokenHeader] = token;
+		return this.client.getAxiosInstance().request(error.config);
 	}
 
 	public dispose(): void {

src/api/axios.d.ts

@@ -0,0 +1,27 @@
+import "axios";
+
+declare module "axios" {
+	interface InternalAxiosRequestConfig {
+		/** Set once the OAuth-refresh or interactive re-auth path has run. */
+		_retryAttempted?: boolean;
+		/**
+		 * Set once the silent auth-config-change retry has run. Separate
+		 * from `_retryAttempted` so a follow-up 401 can still escalate to
+		 * OAuth or interactive re-auth.
+		 */
+		_authConfigRetryAttempted?: boolean;
+		/** Set once a client-certificate error has been retried with refreshed certs. */
+		_certRetried?: boolean;
+		/**
+		 * Auth-config version snapshotted when the request was stamped.
+		 * Compared on a 401 to detect that auth settings changed mid-flight.
+		 */
+		authConfigVersion?: number;
+		/**
+		 * Headers the previous header-command run added to this request.
+		 * Cleared at the start of the next pass so stale keys don't leak
+		 * through when the command output changes between retries.
+		 */
+		headerCommandKeys?: string[];
+	}
+}

src/api/coderApi.ts

@@ -8,7 +8,10 @@ import {
 import { Api } from "coder/site/src/api/api";
 import * as vscode from "vscode";
 
-import { watchConfigurationChanges } from "../configWatcher";
+import {
+	CONFIG_CHANGE_DEBOUNCE_MS,
+	watchConfigurationChanges,
+} from "../configWatcher";
 import { ClientCertificateError } from "../error/clientCertificateError";
 import { toError } from "../error/errorUtils";
 import { ServerCertificateError } from "../error/serverCertificateError";
@@ -26,6 +29,7 @@ import {
 	type RequestConfigWithMeta,
 } from "../logging/types";
 import { sizeOf } from "../logging/utils";
+import { AuthConfigTracker } from "../settings/authConfig";
 import { getHeaderCommand } from "../settings/headers";
 import {
 	NOOP_TELEMETRY_REPORTER,
@@ -98,6 +102,7 @@ export class CoderApi extends Api implements vscode.Disposable {
 		private readonly output: Logger,
 		private readonly telemetry: TelemetryReporter,
 		private readonly httpRequestsTelemetry: HttpRequestsTelemetry,
+		private readonly authConfigTracker: AuthConfigTracker,
 	) {
 		super();
 		this.configWatcher = this.watchConfigChanges();
@@ -117,17 +122,27 @@ export class CoderApi extends Api implements vscode.Disposable {
 		telemetry: TelemetryReporter = NOOP_TELEMETRY_REPORTER,
 	): CoderApi {
 		const httpRequestsTelemetry = new HttpRequestsTelemetry(telemetry);
-		const client = new CoderApi(output, telemetry, httpRequestsTelemetry);
+		const authConfigTracker = new AuthConfigTracker();
+		const client = new CoderApi(
+			output,
+			telemetry,
+			httpRequestsTelemetry,
+			authConfigTracker,
+		);
 		client.setCredentials(baseUrl, token);
 
-		setupInterceptors(client, output, httpRequestsTelemetry);
+		setupInterceptors(client, output, httpRequestsTelemetry, authConfigTracker);
 		return client;
 	}
 
 	getHost(): string | undefined {
 		return this.getAxiosInstance().defaults.baseURL;
 	}
 
+	hasAuthConfigChangedSince(version: number | undefined): boolean {
+		return this.authConfigTracker.hasChangedSince(version);
+	}
+
 	/**
 	 * Set both host and token together. Useful for login/logout/switch to
 	 * avoid triggering multiple reconnection events.
@@ -172,6 +187,7 @@ export class CoderApi extends Api implements vscode.Disposable {
 	 */
 	dispose(): void {
 		this.configWatcher.dispose();
+		this.authConfigTracker.dispose();
 		this.httpRequestsTelemetry.dispose();
 		for (const socket of this.reconnectingSockets) {
 			socket.close();
@@ -189,20 +205,24 @@ export class CoderApi extends Api implements vscode.Disposable {
 			setting,
 			getValue: () => vscode.workspace.getConfiguration().get(setting),
 		}));
-		return watchConfigurationChanges(settings, () => {
-			const socketsToReconnect = [...this.reconnectingSockets].filter(
-				(socket) => socket.state === ConnectionState.DISCONNECTED,
-			);
-			if (socketsToReconnect.length) {
-				this.output.debug(
-					`Configuration changed, ${socketsToReconnect.length}/${this.reconnectingSockets.size} socket(s) in DISCONNECTED state`,
+		return watchConfigurationChanges(
+			settings,
+			() => {
+				const socketsToReconnect = [...this.reconnectingSockets].filter(
+					(socket) => socket.state === ConnectionState.DISCONNECTED,
 				);
-				for (const socket of socketsToReconnect) {
-					this.output.debug(`Reconnecting WebSocket: ${socket.url}`);
-					socket.reconnect();
+				if (socketsToReconnect.length) {
+					this.output.debug(
+						`Configuration changed, ${socketsToReconnect.length}/${this.reconnectingSockets.size} socket(s) in DISCONNECTED state`,
+					);
+					for (const socket of socketsToReconnect) {
+						this.output.debug(`Reconnecting WebSocket: ${socket.url}`);
+						socket.reconnect();
+					}
 				}
-			}
-		});
+			},
+			{ debounceMs: CONFIG_CHANGE_DEBOUNCE_MS },
+		);
 	}
 
 	watchInboxNotifications = async (
@@ -495,6 +515,7 @@ function setupInterceptors(
 	client: CoderApi,
 	output: Logger,
 	httpRequestsTelemetry: HttpRequestsTelemetry,
+	authConfigTracker: AuthConfigTracker,
 ): void {
 	addRequestInterceptors(
 		client.getAxiosInstance(),
@@ -503,20 +524,43 @@ function setupInterceptors(
 	);
 
 	client.getAxiosInstance().interceptors.request.use(async (config) => {
+		// Snapshot the version up front so it matches the config we're about
+		// to read, not whatever it bumps to during the awaits below.
+		config.authConfigVersion = authConfigTracker.version;
+
+		// Drop headers from the prior header-command run so stale keys can't
+		// leak through if the command output changed between attempts.
+		for (const key of config.headerCommandKeys ?? []) {
+			config.headers.delete(key);
+		}
+
 		const baseUrl = client.getAxiosInstance().defaults.baseURL;
 		const headers = await getHeaders(
 			baseUrl,
 			getHeaderCommand(vscode.workspace.getConfiguration()),
 			output,
 		);
-		// Add headers from the header command.
+		const retrying =
+			config._retryAttempted === true ||
+			config._authConfigRetryAttempted === true;
 		for (const [key, value] of Object.entries(headers)) {
+			// On retry, don't let stale command output overwrite the session
+			// token retryRequest just wrote.
+			if (
+				retrying &&
+				key.toLowerCase() === coderSessionTokenHeader.toLowerCase()
+			) {
+				continue;
+			}
 			config.headers[key] = value;
 		}
+		// Don't track the session token: cleanup must never touch it.
+		config.headerCommandKeys = Object.keys(headers).filter(
+			(k) => k.toLowerCase() !== coderSessionTokenHeader.toLowerCase(),
+		);
 
-		// Configure proxy and TLS.
-		// Note that by default VS Code overrides the agent. To prevent this, set
-		// `http.proxySupport` to `on` or `off`.
+		// VS Code overrides the agent by default; set `http.proxySupport` to
+		// `on` or `off` to keep ours.
 		const agent = await createHttpAgent(vscode.workspace.getConfiguration());
 		config.httpsAgent = agent;
 		config.httpAgent = agent;
@@ -626,13 +670,10 @@ async function tryRefreshClientCertificate(
 	}
 
 	// _certRetried is per-request (Axios creates fresh config per request).
-	const config = err.config as RequestConfigWithMeta & {
-		_certRetried?: boolean;
-	};
-	if (config._certRetried) {
+	if (err.config._certRetried) {
 		throw certError;
 	}
-	config._certRetried = true;
+	err.config._certRetried = true;
 
 	output.info(
 		`Client certificate error (alert ${certError.alertCode}), attempting refresh...`,
@@ -644,12 +685,12 @@ async function tryRefreshClientCertificate(
 
 	// Create new agent with refreshed certificates.
 	const agent = await createHttpAgent(vscode.workspace.getConfiguration());
-	config.httpsAgent = agent;
-	config.httpAgent = agent;
+	err.config.httpsAgent = agent;
+	err.config.httpAgent = agent;
 
 	// Retry the request.
 	output.info("Retrying request with refreshed certificates...");
-	return axiosInstance.request(config);
+	return axiosInstance.request(err.config);
 }
 
 function wrapRequestTransform(

src/configWatcher.ts

@@ -1,43 +1,70 @@
 import { isDeepStrictEqual } from "node:util";
 import * as vscode from "vscode";
 
+/** Idle window for config-change reactions. Coalesces rapid edits into one fire. */
+export const CONFIG_CHANGE_DEBOUNCE_MS = 200;
+
 export interface WatchedSetting {
 	setting: string;
 	getValue: () => unknown;
 }
 
+export interface WatchConfigurationChangesOptions {
+	/**
+	 * Idle window in ms. Each new event resets the timer; the callback
+	 * fires once settings have been quiet for this long. Unset means fire
+	 * synchronously on every event.
+	 */
+	debounceMs?: number;
+}
+
 /**
- * Watch for configuration changes and invoke a callback when values change.
- * The callback receives a map of changed settings to their new values, so
- * consumers can act on the new value without re-reading the configuration.
- * Only fires when actual values change, not just when settings are touched.
+ * Watch for configuration changes and fire when watched values change.
+ * With `debounceMs`, defers until settings have been quiet for that long.
  */
 export function watchConfigurationChanges(
 	settings: WatchedSetting[],
 	onChange: (changes: ReadonlyMap<string, unknown>) => void,
+	options: WatchConfigurationChangesOptions = {},
 ): vscode.Disposable {
 	const appliedValues = new Map(settings.map((s) => [s.setting, s.getValue()]));
 
-	return vscode.workspace.onDidChangeConfiguration((e) => {
+	const detectAndFire = () => {
 		const changes = new Map<string, unknown>();
-
 		for (const { setting, getValue } of settings) {
-			if (!e.affectsConfiguration(setting)) {
-				continue;
-			}
-
 			const newValue = getValue();
-
 			if (!configValuesEqual(newValue, appliedValues.get(setting))) {
 				changes.set(setting, newValue);
 				appliedValues.set(setting, newValue);
 			}
 		}
-
 		if (changes.size > 0) {
 			onChange(changes);
 		}
+	};
+
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	const listener = vscode.workspace.onDidChangeConfiguration((e) => {
+		if (!settings.some((s) => e.affectsConfiguration(s.setting))) {
+			return;
+		}
+		if (!options.debounceMs) {
+			detectAndFire();
+			return;
+		}
+		clearTimeout(idleTimer);
+		idleTimer = setTimeout(() => {
+			idleTimer = undefined;
+			detectAndFire();
+		}, options.debounceMs);
 	});
+
+	return {
+		dispose: () => {
+			clearTimeout(idleTimer);
+			listener.dispose();
+		},
+	};
 }
 
 function configValuesEqual(a: unknown, b: unknown): boolean {