health: classify Google disabled-API 403 as misconfigured, not expired

RhysSullivan · RhysSullivan · commit ee67b0ef81e7 · 2026-07-10T15:37:37.000-07:00
A SERVICE_DISABLED / accessNotConfigured 403 means the API is disabled in
the OAuth client's project; the credential is fine. Probes now classify it
as a new 'misconfigured' status: amber 'API disabled' badge, the provider's
own remediation text (console link clickable) on the row, and no reconnect
prompt.
diff --git a/e2e/scenarios/google-disabled-api.test.ts b/e2e/scenarios/google-disabled-api.test.ts
@@ -1,22 +1,21 @@
-// Repro: a Google 403 for a DISABLED API reads as an expired credential.
+// A Google 403 for a DISABLED API must NOT read as an expired credential.
 //
 // Production case (2026-07-10): a user's "Personal Google" connection showed
 // the red Expired badge although its OAuth token was alive and refreshing.
 // The org's Google OAuth client lives in a GCP project without the Gmail /
 // Drive / Calendar APIs enabled, so the health probe gets Google's
 // SERVICE_DISABLED 403 ("Gmail API has not been used in project ... or it is
-// disabled"). `classifyHttpStatus` maps every 401/403 to "expired", so a
-// perfectly healthy credential renders as Expired and the UI tells the user
-// to reconnect - which cannot fix a disabled upstream API.
+// disabled"). The old status-only classifier mapped every 401/403 to
+// "expired", so a healthy credential rendered as Expired and the UI told the
+// user to reconnect - advice that cannot fix a disabled upstream API.
 //
 // The scenario replays that exact journey against the Google emulator: a real
 // OAuth grant probes healthy; then the upstream starts answering the probe
 // operation with Google's real SERVICE_DISABLED body (fault injection - the
-// token stays valid, exactly like prod); the connection now reads Expired on
-// screen with the reconnect toast. The assertions pin today's (wrong)
-// classification on purpose: when the classifier learns to tell "API disabled
-// in the project" from "credential expired", this scenario is the one that
-// must change.
+// token stays valid, exactly like prod). The fixed classifier reads the error
+// body and reports "misconfigured": on screen that is the amber "API
+// disabled" badge with Google's own remediation text (including the console
+// link that enables the API), and no reconnect prompt.
 import { randomBytes } from "node:crypto";
 
 import { expect } from "@effect/vitest";
@@ -205,7 +204,7 @@ const connectGoogleAccount = (input: {
   });
 
 scenario(
-  "Google · repro: a disabled upstream API reads as an expired connection (SERVICE_DISABLED 403)",
+  "Google · a disabled upstream API reads as API disabled with the enable link, not Expired",
   { timeout: 300_000 },
   Effect.gen(function* () {
     const target = yield* Target;
@@ -259,16 +258,16 @@ scenario(
         );
         yield* Effect.promise(() => emulator.client.ledger.clear());
 
-        // THE BUG, pinned: a 403 that means "enable this API in your GCP
-        // project" classifies as an expired credential.
+        // The fix under test: a 403 that means "enable this API in your GCP
+        // project" classifies as misconfigured, not as a dead credential.
         const verdict = yield* client.connections.checkHealth({
           params: { owner: "org", integration: slug, name: CONNECTION },
           query: { ifStaleMs: 0 },
         });
         expect(
           verdict.status,
-          "BUG: the SERVICE_DISABLED 403 classifies as an expired credential",
-        ).toBe("expired");
+          `the SERVICE_DISABLED 403 classifies as misconfigured: ${JSON.stringify(verdict)}`,
+        ).toBe("misconfigured");
         expect(verdict.httpStatus, "the probe observed the 403").toBe(403);
         expect(
           verdict.detail,
@@ -287,24 +286,49 @@ scenario(
           });
 
           await step(
-            "The healthy-yesterday connection now shows Expired, with no clicks",
+            "The connection shows the amber API disabled badge - not Expired - with no clicks",
             async () => {
               await page.goto(`/integrations/${slug}`, { waitUntil: "networkidle" });
-              await connections.getByText("Expired", { exact: true }).waitFor({ timeout: 30_000 });
-              await connections.getByLabel("Status: Expired").waitFor();
+              await connections
+                .getByText("API disabled", { exact: true })
+                .waitFor({ timeout: 30_000 });
+              await connections.getByLabel("Status: API disabled").waitFor();
+              // The dead-credential story must be gone entirely.
+              expect(
+                await connections.getByText("Expired", { exact: true }).count(),
+                "no Expired badge on a misconfigured connection",
+              ).toBe(0);
+            },
+          );
+
+          await step(
+            "The row carries Google's own instruction, console link included",
+            async () => {
+              await connections.getByText(/has not been used in project/).waitFor();
+              const consoleLink = connections.getByRole("link", {
+                name: /console\.developers\.google\.com/,
+              });
+              await consoleLink.waitFor();
+              expect(
+                await consoleLink.getAttribute("href"),
+                "the enable-API console link is clickable",
+              ).toContain("console.developers.google.com");
             },
           );
 
           await step(
-            "Check now tells the user to reconnect - advice that cannot fix a disabled API",
+            "Check now explains the disabled API instead of prescribing reconnect",
             async () => {
               await connections.locator('button[aria-haspopup="menu"]').click();
               await page.getByRole("menuitem", { name: "Check now" }).click();
-              // The misleading UX in one line: the toast prescribes reconnecting
-              // while the upstream error says "enable the API in your project".
               await page
-                .getByText("Connection expired, reconnect to restore access")
+                .getByText(/has not been used in project/)
+                .first()
                 .waitFor({ timeout: 30_000 });
+              expect(
+                await page.getByText("Connection expired, reconnect to restore access").count(),
+                "the reconnect toast never fires for a configuration 403",
+              ).toBe(0);
             },
           );
         });
diff --git a/packages/core/sdk/src/health-check.test.ts b/packages/core/sdk/src/health-check.test.ts
@@ -5,6 +5,8 @@ import { describe, expect, it } from "@effect/vitest";
 
 import {
   candidateIdentityTier,
+  classifyHttpStatus,
+  classifyProbeResponse,
   rankResponseSample,
   sortHealthCheckCandidatesByIdentity,
 } from "./health-check";
@@ -66,3 +68,73 @@ describe("candidateIdentityTier", () => {
     ).toBe("user.getAuthUser");
   });
 });
+
+// Probe classification: 401/403 mean "credential dead" EXCEPT the
+// configuration 403 (Google accessNotConfigured / SERVICE_DISABLED), which
+// must read misconfigured: the token authenticated, the API is disabled in
+// the OAuth client's project, and reconnecting cannot fix it. This is the
+// production case behind the "Expired when it is not" report (2026-07-10).
+describe("classifyProbeResponse", () => {
+  const disabledMessage =
+    "Gmail API has not been used in project 000000000000 before or it is disabled. " +
+    "Enable it by visiting https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=000000000000 then retry.";
+
+  it("classifies Google's classic accessNotConfigured 403 as misconfigured", () => {
+    const body = {
+      error: {
+        code: 403,
+        message: disabledMessage,
+        errors: [
+          { message: disabledMessage, domain: "usageLimits", reason: "accessNotConfigured" },
+        ],
+        status: "PERMISSION_DENIED",
+      },
+    };
+    expect(classifyProbeResponse(403, body)).toBe("misconfigured");
+  });
+
+  it("classifies the newer SERVICE_DISABLED ErrorInfo detail as misconfigured", () => {
+    const body = {
+      error: {
+        code: 403,
+        message: disabledMessage,
+        status: "PERMISSION_DENIED",
+        details: [
+          {
+            "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+            reason: "SERVICE_DISABLED",
+            domain: "googleapis.com",
+          },
+        ],
+      },
+    };
+    expect(classifyProbeResponse(403, body)).toBe("misconfigured");
+  });
+
+  it("keeps a plain 403 (no recognized reason) as expired: false-expired is the safe default", () => {
+    expect(classifyProbeResponse(403, { error: { code: 403, message: "Forbidden" } })).toBe(
+      "expired",
+    );
+    expect(classifyProbeResponse(403, undefined)).toBe("expired");
+    expect(classifyProbeResponse(403, "Forbidden")).toBe("expired");
+    // A permission reason that is NOT a configuration marker stays expired.
+    expect(
+      classifyProbeResponse(403, {
+        error: { errors: [{ reason: "insufficientPermissions" }] },
+      }),
+    ).toBe("expired");
+  });
+
+  it("never rewrites a 401: an authentication failure is a credential problem regardless of body", () => {
+    const body = { error: { errors: [{ reason: "accessNotConfigured" }] } };
+    expect(classifyProbeResponse(401, body)).toBe("expired");
+  });
+
+  it("matches the status-only classifier everywhere else", () => {
+    for (const status of [200, 204, 404, 429, 500, 503]) {
+      expect(classifyProbeResponse(status, { error: {} }), `status ${status}`).toBe(
+        classifyHttpStatus(status),
+      );
+    }
+  });
+});
diff --git a/packages/core/sdk/src/health-check.ts b/packages/core/sdk/src/health-check.ts
@@ -18,14 +18,24 @@
 import { Schema } from "effect";
 
 // ---------------------------------------------------------------------------
-// Status: the four states a connection can be in. `expired` is the one this
+// Status: the five states a connection can be in. `expired` is the one this
 // whole feature exists for (Google's 7-day dev-token revocation): the credential
-// authenticated fine yesterday and now returns 401/403. `degraded` covers any
-// other non-2xx (upstream 5xx, a 404 on a mis-picked operation); `unknown` is
-// "never checked / no health check configured".
+// authenticated fine yesterday and now returns 401/403. `misconfigured` is the
+// 403 that is NOT a credential problem: the token authenticated, but the
+// upstream rejects on configuration (a Google API not enabled in the OAuth
+// client's GCP project): the fix is in the provider console, so telling the
+// user to reconnect would mislead. `degraded` covers any other non-2xx
+// (upstream 5xx, a 404 on a mis-picked operation); `unknown` is "never checked
+// / no health check configured".
 // ---------------------------------------------------------------------------
 
-export const HealthStatus = Schema.Literals(["healthy", "expired", "degraded", "unknown"]);
+export const HealthStatus = Schema.Literals([
+  "healthy",
+  "expired",
+  "misconfigured",
+  "degraded",
+  "unknown",
+]);
 export type HealthStatus = typeof HealthStatus.Type;
 
 // ---------------------------------------------------------------------------
@@ -139,13 +149,59 @@ export type HealthCheckCandidate = typeof HealthCheckCandidate.Type;
 // ---------------------------------------------------------------------------
 
 /** Map an HTTP status to a health state: 2xx healthy, 401/403 expired (the auth
- *  wall), everything else degraded. */
+ *  wall), everything else degraded. Status-only fallback: when the response
+ *  BODY is available, use `classifyProbeResponse` instead, which tells a
+ *  credential 403 apart from a configuration 403. */
 export const classifyHttpStatus = (status: number): HealthStatus => {
   if (status >= 200 && status < 300) return "healthy";
   if (status === 401 || status === 403) return "expired";
   return "degraded";
 };
 
+// Error `reason` / `status` markers that make a 403 a CONFIGURATION rejection
+// rather than a credential one. Deliberately narrow and provider-shaped:
+// Google's error envelope carries `errors[].reason: "accessNotConfigured"`
+// (message "<API> has not been used in project N before or it is disabled")
+// and newer surfaces use `status: "PERMISSION_DENIED"` with
+// `details[].reason: "SERVICE_DISABLED"`. Unrecognized 403s keep the expired
+// classification: a false "expired" prompts a harmless reconnect, but a false
+// "misconfigured" would hide a genuinely dead credential.
+const CONFIGURATION_403_REASONS = new Set(["accessnotconfigured", "service_disabled"]);
+
+/** Collect candidate `reason` markers from a Google-shaped error envelope:
+ *  `error.errors[].reason` (classic) and `error.details[].reason` (newer
+ *  google.rpc.ErrorInfo). Tolerant of partial shapes; returns []. */
+const errorReasonMarkers = (body: unknown): string[] => {
+  if (body == null || typeof body !== "object") return [];
+  const error = (body as Record<string, unknown>)["error"];
+  if (error == null || typeof error !== "object") return [];
+  const markers: string[] = [];
+  for (const key of ["errors", "details"] as const) {
+    const entries = (error as Record<string, unknown>)[key];
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry == null || typeof entry !== "object") continue;
+      const reason = (entry as Record<string, unknown>)["reason"];
+      if (typeof reason === "string") markers.push(reason.toLowerCase());
+    }
+  }
+  return markers;
+};
+
+/** Classify a probe response from its status AND body. Everything is
+ *  `classifyHttpStatus` except one carve-out: a 403 whose error body carries a
+ *  known configuration reason (Google `accessNotConfigured` /
+ *  `SERVICE_DISABLED`) is `misconfigured`, not `expired`: the credential
+ *  authenticated; the upstream API is disabled in the OAuth client's project,
+ *  and only enabling it there (not reconnecting) fixes it. */
+export const classifyProbeResponse = (status: number, body: unknown): HealthStatus => {
+  const byStatus = classifyHttpStatus(status);
+  if (status !== 403 || byStatus !== "expired") return byStatus;
+  return errorReasonMarkers(body).some((reason) => CONFIGURATION_403_REASONS.has(reason))
+    ? "misconfigured"
+    : "expired";
+};
+
 /** Resolve a dot-path (`a.b.0.c`) against a JSON value and coerce the leaf to a
  *  display string. Numeric segments index arrays. Returns undefined when the
  *  path is empty, missing, or lands on a non-scalar. */
diff --git a/packages/core/sdk/src/index.ts b/packages/core/sdk/src/index.ts
@@ -114,6 +114,7 @@ export {
   HealthCheckCandidateParameter,
   HealthCheckResponseField,
   classifyHttpStatus,
+  classifyProbeResponse,
   extractIdentity,
   compareHealthCheckCandidates,
   candidateIdentityTier,
diff --git a/packages/core/sdk/src/shared.ts b/packages/core/sdk/src/shared.ts
@@ -118,6 +118,7 @@ export {
   HealthCheckCandidate,
   HealthCheckCandidateParameter,
   classifyHttpStatus,
+  classifyProbeResponse,
   extractIdentity,
   compareHealthCheckCandidates,
   candidateIdentityTier,
diff --git a/packages/plugins/openapi/src/sdk/backing.ts b/packages/plugins/openapi/src/sdk/backing.ts
@@ -7,7 +7,7 @@ import {
   ToolName,
   ToolResult,
   authToolFailure,
-  classifyHttpStatus,
+  classifyProbeResponse,
   detectInsufficientScope,
   sortHealthCheckCandidatesByIdentity,
   extractIdentity,
@@ -962,7 +962,9 @@ export const checkHealthOpenApi = (input: {
       } satisfies HealthCheckResult;
     }
 
-    const status = classifyHttpStatus(probe.result.status);
+    // Body-aware: a configuration 403 (Google accessNotConfigured /
+    // SERVICE_DISABLED) reads misconfigured, not expired.
+    const status = classifyProbeResponse(probe.result.status, probe.result.error);
     const identity =
       status === "healthy" ? extractIdentity(probe.result.data, spec.identityField) : undefined;
     // Sample the returned body ONLY on a healthy probe: the sample exists to
diff --git a/packages/react/src/components/accounts-section.tsx b/packages/react/src/components/accounts-section.tsx
diff --git a/packages/react/src/components/add-account-modal.tsx b/packages/react/src/components/add-account-modal.tsx
diff --git a/packages/react/src/lib/health-display.ts b/packages/react/src/lib/health-display.ts
