Support webserver-level HTTP Basic Auth in front of CiviCRM

app/api/health/route.ts

@@ -36,12 +36,61 @@ function envSummary(): CheckResult {
   };
   const ok = have.CIVI_BASE_URL && have.CIVI_API_KEY && have.CIVI_SITE_KEY;
   const baseUrl = process.env.CIVI_BASE_URL ?? "(unset)";
+  const basicAuth =
+    process.env.CIVI_HTTP_AUTH_USER && process.env.CIVI_HTTP_AUTH_PASS
+      ? `set (${process.env.CIVI_HTTP_AUTH_USER})`
+      : "not set";
   const detail = ok
-    ? `All three env vars present. CIVI_BASE_URL=${baseUrl}`
+    ? `Civi env vars present. CIVI_BASE_URL=${baseUrl}. HTTP Basic Auth: ${basicAuth}.`
     : `Missing: ${Object.entries(have).filter(([, v]) => !v).map(([k]) => k).join(", ") || "(none)"}. STUB MODE active.`;
   return { check: "env_vars", ok, detail };
 }
 
+async function probeWebserverReachable(): Promise<CheckResult> {
+  // Detects the "Apache 401 in front of Civi" pattern specifically. We GET
+  // the base URL with the same auth headers we'd send to APIv4. If the
+  // webserver itself rejects (401 + HTML body), it's an htaccess basic-auth
+  // wall and we need CIVI_HTTP_AUTH_USER / CIVI_HTTP_AUTH_PASS.
+  try {
+    const headers: Record<string, string> = {};
+    if (process.env.CIVI_HTTP_AUTH_USER && process.env.CIVI_HTTP_AUTH_PASS) {
+      const creds = Buffer.from(
+        `${process.env.CIVI_HTTP_AUTH_USER}:${process.env.CIVI_HTTP_AUTH_PASS}`,
+      ).toString("base64");
+      headers["Authorization"] = `Basic ${creds}`;
+    }
+    const res = await fetch(`${process.env.CIVI_BASE_URL}/civicrm`, {
+      method: "GET",
+      headers,
+      cache: "no-store",
+      redirect: "manual",
+    });
+    if (res.status === 401) {
+      const auth = res.headers.get("www-authenticate") ?? "";
+      return {
+        check: "webserver_reachable",
+        ok: false,
+        detail:
+          `Webserver returned 401 from ${process.env.CIVI_BASE_URL}/civicrm. ` +
+          `WWW-Authenticate: "${auth}". ` +
+          `This is an HTTP Basic Auth wall in front of CiviCRM (Apache/htaccess). ` +
+          `Set CIVI_HTTP_AUTH_USER and CIVI_HTTP_AUTH_PASS in .env.local.`,
+      };
+    }
+    return {
+      check: "webserver_reachable",
+      ok: res.status < 500,
+      detail: `GET /civicrm → HTTP ${res.status}.`,
+    };
+  } catch (e) {
+    return {
+      check: "webserver_reachable",
+      ok: false,
+      detail: e instanceof Error ? e.message : String(e),
+    };
+  }
+}
+
 async function probeContactGet(): Promise<CheckResult> {
   try {
     const res = await civi("Contact", "get", {
@@ -223,15 +272,27 @@ export async function GET(req: Request) {
 
   const checks: CheckResult[] = [env];
 
-  // Run independent probes in parallel.
-  const probes = await Promise.all([
-    probeContactGet(),
-    probeRelationshipType(),
-    probeActivityType(),
-    probeStageOptionGroup(),
-    probeChecksumApi(),
-  ]);
-  checks.push(...probes);
+  // Webserver probe first — if this fails, the others will too. We run it
+  // serially so we get a clean "fix this first" signal at the top.
+  const webserver = await probeWebserverReachable();
+  checks.push(webserver);
+
+  if (webserver.ok) {
+    const probes = await Promise.all([
+      probeContactGet(),
+      probeRelationshipType(),
+      probeActivityType(),
+      probeStageOptionGroup(),
+      probeChecksumApi(),
+    ]);
+    checks.push(...probes);
+  } else {
+    checks.push({
+      check: "civi_probes_skipped",
+      ok: false,
+      detail: "Skipped Civi-level probes because the webserver itself rejected the request. Fix webserver_reachable above first.",
+    });
+  }
 
   // If a sample cid+cs was provided, verify that specific checksum.
   if (cid && cs) {