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

.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

@@ -71,6 +71,40 @@ describe('healthCheck/validateFaustEnvVars', () => {
 			`Ensure your FAUST_SECRET_KEY environment variable matches your Secret Key in the Faust WordPress plugin settings`,
 		);
 	});
+
+	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', () => {