fix[faustwp-cli]: (#1850) detect HTTP Basic Auth and show accurate error

When a WordPress site is protected with HTTP Basic Authentication,
the secret key validation request returns 401 from the web server,
not from FaustWP. The health check assumed any 401 meant the secret
key was wrong, showing a misleading error message.

Check the WWW-Authenticate response header for "Basic" to distinguish
HTTP Basic Auth (web server) from a secret key mismatch (plugin).
Show a specific error message telling the user their site has Basic
Auth protection.

Closes #1850

Author: latenighthackathon

.changeset/basic-auth-error-message.md

@@ -0,0 +1,5 @@
+---
+"@faustwp/cli": patch
+---
+
+fix[faustwp-cli]: detect HTTP Basic Auth on 401 response and show accurate error message instead of misleading secret key mismatch

packages/faustwp-cli/src/healthCheck/validateFaustEnvVars.ts

@@ -58,10 +58,19 @@ export const validateFaustEnvVars = async () => {
 				method: 'POST',
 			});
 			if (response.status === 401) {
-				// Unauthorized: User receives a 401 status code AND the message below
-				errorLog(
-					'Ensure your FAUST_SECRET_KEY environment variable matches your Secret Key in the Faust WordPress plugin settings',
-				);
+				const wwwAuth = response.headers.get('www-authenticate') || '';
+				if (wwwAuth.toLowerCase().includes('basic')) {
+					errorLog(
+						'Your WordPress site appears to be protected with HTTP Basic Authentication.',
+					);
+					errorLog(
+						'Faust cannot validate the secret key until Basic Auth credentials are provided or the protection is removed.',
+					);
+				} else {
+					errorLog(
+						'Ensure your FAUST_SECRET_KEY environment variable matches your Secret Key in the Faust WordPress plugin settings',
+					);
+				}
 				process.exit(1);
 			}
 			await validateNextWordPressUrl();

packages/faustwp-cli/tests/healthCheck/validateFaustEnvVars.test.ts

@@ -73,6 +73,41 @@ describe('healthCheck/validateFaustEnvVars', () => {
 	});
 });
 
+
+	it('logs a Basic Auth error when the site returns 401 with WWW-Authenticate: Basic', async () => {
+		// @ts-ignore
+		const mockExit = jest.spyOn(process, 'exit').mockImplementation((code) => {
+			if (code && code !== 0) {
+				throw new Error(`Exit code: ${code}`);
+			}
+		});
+		const mockLog = jest.spyOn(console, 'log').mockImplementation(() => {});
+
+		process.env.NEXT_PUBLIC_WORDPRESS_URL = 'https://basicauth.local';
+		process.env.FAUST_SECRET_KEY = 'valid-secret-key';
+
+		fetchMock.post(
+			'https://basicauth.local/?rest_route=/faustwp/v1/validate_secret_key',
+			{
+				status: 401,
+				headers: { 'WWW-Authenticate': 'Basic realm="Restricted"' },
+			},
+		);
+
+		try {
+			await validateFaustEnvVars();
+		} catch (err) {
+			// Expected exit
+		}
+
+		expect(mockExit).toHaveBeenCalledWith(1);
+		expect(mockLog).toHaveBeenCalledWith(
+			expect.stringContaining('HTTP Basic Authentication'),
+		);
+
+		mockLog.mockRestore();
+	});
+
 describe('isWPEngineComTLD', () => {
 	it('matches subdomains on wpengine.com', () => {
 		expect(isWPEngineComSubdomain('https://my-site.wpengine.com')).toBeTruthy();