Block OAuth setup bypass for definitive auth failures

Ctrl+S save-anyway must not persist staged Codex/xAI credentials after
insufficient-scope or revoked refresh rejection. Transient refresh
failures stay inconclusive so existing save-anyway UX remains.

Author: TheGreatAxios

src/auth/oauth-scope-check.test.ts

@@ -62,30 +62,43 @@ describe("checkOAuthProviderScope", () => {
     expect(expired.access).toBe("refreshed-codex");
   });
 
-  test("codex: reports an expired staged token refresh failure as unavailable", async () => {
+  test("codex: blocks a definitive staged refresh rejection", async () => {
     const expired = { ...codexTokens, expiresAt: 0 };
-    stubFetch(() => new Response("refresh rejected", { status: 401 }));
+    stubFetch(() => new Response(JSON.stringify({ error: "invalid_grant" }), { status: 400 }));
+
+    const result = await checkOAuthProviderScope("codex", expired);
+
+    expect(result.status).toBe("blocked");
+    if (result.status === "blocked") {
+      expect(result.message).toMatch(/expired|revoked/i);
+    }
+  });
+
+  test("codex: reports a transient staged refresh failure as unavailable", async () => {
+    const expired = { ...codexTokens, expiresAt: 0 };
+    stubFetch(() => {
+      throw new Error("network down");
+    });
 
     const result = await checkOAuthProviderScope("codex", expired);
 
     expect(result.status).toBe("unavailable");
   });
 
-  test("codex: insufficient-scope on a definitive 403", async () => {
+  test("codex: blocks a definitive 403 without surfacing the raw body", async () => {
     stubFetch(() => new Response("forbidden", { status: 403 }));
     const result = await checkOAuthProviderScope("codex", codexTokens);
-    expect(result.status).toBe("insufficient-scope");
-    if (result.status === "insufficient-scope") {
+    expect(result.status).toBe("blocked");
+    if (result.status === "blocked") {
       expect(result.message).toMatch(/reconnect/i);
-      // Must never surface the raw response body.
       expect(result.message).not.toContain("forbidden");
     }
   });
 
-  test("codex: insufficient-scope on a definitive 401", async () => {
+  test("codex: blocks a definitive 401", async () => {
     stubFetch(() => new Response("nope", { status: 401 }));
     const result = await checkOAuthProviderScope("codex", codexTokens);
-    expect(result.status).toBe("insufficient-scope");
+    expect(result.status).toBe("blocked");
   });
 
   test("codex: unavailable on a network failure, not blocked", async () => {
@@ -133,19 +146,33 @@ describe("checkOAuthProviderScope", () => {
     expect(expired.access).toBe("refreshed-xai");
   });
 
-  test("xai: reports an expired staged token refresh failure as unavailable", async () => {
+  test("xai: blocks a definitive staged refresh rejection", async () => {
     const expired = { ...xaiTokens, expiresAt: 0 };
-    stubFetch(() => new Response("refresh rejected", { status: 401 }));
+    stubFetch(() => new Response(JSON.stringify({ error: "revoked" }), { status: 401 }));
+
+    const result = await checkOAuthProviderScope("xai", expired);
+
+    expect(result.status).toBe("blocked");
+    if (result.status === "blocked") {
+      expect(result.message).toMatch(/expired|revoked/i);
+    }
+  });
+
+  test("xai: reports a transient staged refresh failure as unavailable", async () => {
+    const expired = { ...xaiTokens, expiresAt: 0 };
+    stubFetch(() => {
+      throw new DOMException("The operation timed out.", "TimeoutError");
+    });
 
     const result = await checkOAuthProviderScope("xai", expired);
 
     expect(result.status).toBe("unavailable");
   });
 
-  test("xai: insufficient-scope on a definitive 403", async () => {
+  test("xai: blocks a definitive 403", async () => {
     stubFetch(() => new Response("forbidden", { status: 403 }));
     const result = await checkOAuthProviderScope("xai", xaiTokens);
-    expect(result.status).toBe("insufficient-scope");
+    expect(result.status).toBe("blocked");
   });
 
   test("xai: unavailable on a timeout-style abort", async () => {

src/auth/oauth-scope-check.ts

@@ -18,12 +18,13 @@ import { XAI_BASE_URL, XAI_TOKEN_TIMEOUT_MS } from "./xai/constants.js";
 import { refreshStagedXaiTokens } from "./xai/session.js";
 import type { XaiTokens } from "./xai/store.js";
 import { xaiAuthHeadersForToken } from "./xai/usage.js";
+import { OAuthTokenEndpointError } from "./oauth/client.js";
 
 export type OAuthScopeCheckKind = "codex" | "xai";
 
 export type OAuthScopeCheckResult =
   | { status: "ok" }
-  | { status: "insufficient-scope"; message: string }
+  | { status: "blocked"; message: string }
   // The probe could not run to completion (network blip, timeout, rate
   // limit, provider hiccup). This must never be treated the same as a
   // definitive scope failure — a transient failure must not lock a
@@ -34,7 +35,7 @@ const SCOPE_CHECK_TIMEOUT_MS = 10_000;
 
 function insufficientScope(providerLabel: string): OAuthScopeCheckResult {
   return {
-    status: "insufficient-scope",
+    status: "blocked",
     message:
       `Your ${providerLabel} sign-in doesn't carry API access (it looks like a chat-only plan). ` +
       `Reconnect ${providerLabel} with an account/plan that includes API access, then try again.`,
@@ -48,6 +49,36 @@ function unavailable(providerLabel: string): OAuthScopeCheckResult {
   };
 }
 
+function invalidCredentials(providerLabel: string): OAuthScopeCheckResult {
+  return {
+    status: "blocked",
+    message: `${providerLabel} sign-in expired or was revoked. Reconnect ${providerLabel}, then try again.`,
+  };
+}
+
+export class OAuthProviderScopeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OAuthProviderScopeError";
+  }
+}
+
+export function isOAuthProviderScopeError(err: unknown): err is OAuthProviderScopeError {
+  return err instanceof OAuthProviderScopeError;
+}
+
+export function isBlockingOAuthScopeCheckResult(
+  result: OAuthScopeCheckResult,
+): result is Extract<OAuthScopeCheckResult, { status: "blocked" }> {
+  return result.status === "blocked";
+}
+
+function isDefinitiveRefreshAuthRejection(err: unknown): boolean {
+  if (!(err instanceof OAuthTokenEndpointError)) return false;
+  if (err.status === 401 || err.status === 403) return true;
+  return /invalid_grant|revoked/i.test(err.detail);
+}
+
 // 401/403 is the provider definitively rejecting the token for this surface —
 // treated as a real scope failure. Anything else (429, 5xx, a malformed
 // response) is inconclusive: it says nothing about whether the token has
@@ -68,7 +99,8 @@ async function checkCodexScope(tokens: CodexTokens): Promise<OAuthScopeCheckResu
     });
     if (res.ok) return { status: "ok" };
     return classifyStatus(res.status, providerLabel);
-  } catch {
+  } catch (err) {
+    if (isDefinitiveRefreshAuthRejection(err)) return invalidCredentials(providerLabel);
     return unavailable(providerLabel);
   }
 }
@@ -83,7 +115,8 @@ async function checkXaiScope(tokens: XaiTokens): Promise<OAuthScopeCheckResult>
     });
     if (res.ok) return { status: "ok" };
     return classifyStatus(res.status, providerLabel);
-  } catch {
+  } catch (err) {
+    if (isDefinitiveRefreshAuthRejection(err)) return invalidCredentials(providerLabel);
     return unavailable(providerLabel);
   }
 }

src/auth/oauth/client.ts

@@ -49,6 +49,18 @@ export const TokenResponseSchema = type({
 });
 export type TokenResponse = typeof TokenResponseSchema.infer;
 
+export class OAuthTokenEndpointError extends Error {
+  readonly status: number;
+  readonly detail: string;
+
+  constructor(label: string, status: number, detail: string) {
+    super(`${label} token endpoint returned ${String(status)}${detail ? `: ${detail}` : ""}`);
+    this.name = "OAuthTokenEndpointError";
+    this.status = status;
+    this.detail = detail;
+  }
+}
+
 // Default access-token lifetime when the server omits expires_in. Conservative
 // so the refresh path engages sooner rather than trusting a stale token.
 const DEFAULT_EXPIRES_IN_S = 3600;
@@ -92,9 +104,7 @@ export async function postToken(
   });
   if (!res.ok) {
     const detail = await res.text().catch(() => "");
-    throw new Error(
-      `${config.label} token endpoint returned ${String(res.status)}${detail ? `: ${detail}` : ""}`,
-    );
+    throw new OAuthTokenEndpointError(config.label, res.status, detail);
   }
   // AbortSignal.timeout throws a DOMException (name "TimeoutError") when it
   // fires; its message ("The operation timed out") is what callers report.

src/tui/provider-setup-submit.test.ts

@@ -8,7 +8,7 @@ import { withMockedModule } from "../../tests/helpers/mock-module.js";
 
 // The oauth branch probes real provider scope over the network; stub the
 // check so these tests exercise buildProviderSubmitHandler's own branching
-// (ok / insufficient-scope / unavailable) without a live call.
+// (ok / blocked / unavailable) without a live call.
 let scopeCheckResult: OAuthScopeCheckResult = { status: "ok" };
 const scopeCheckCalls: unknown[][] = [];
 await withMockedModule(
@@ -39,10 +39,9 @@ function stagedCodexOAuth(commit: () => Promise<void> = async () => {}): OAuthRe
   return {
     kind: "codex",
     providerName: "codex/work",
-    profile: "work",
     tokens: stagedCodexTokens,
     commit,
-  } as OAuthResult;
+  };
 }
 
 async function withTempDir(run: (dir: string) => Promise<void>): Promise<void> {
@@ -345,7 +344,7 @@ describe("buildProviderSubmitHandler", () => {
     test("fresh insufficient scope persists no credential or restart selection", async () => {
       await withTempDir(async (dir) => {
         scopeCheckResult = {
-          status: "insufficient-scope",
+          status: "blocked",
           message: "Your Codex sign-in doesn't carry API access. Reconnect Codex and try again.",
         };
         const path = join(dir, "settings.json");
@@ -378,9 +377,45 @@ describe("buildProviderSubmitHandler", () => {
       });
     });
 
+    test("invalid staged OAuth credentials persist no credential or restart selection", async () => {
+      await withTempDir(async (dir) => {
+        scopeCheckResult = {
+          status: "blocked",
+          message: "Codex sign-in expired or was revoked. Reconnect Codex, then try again.",
+        };
+        const path = join(dir, "settings.json");
+        const localPath = localSettingsPath(dir);
+        const submit = buildProviderSubmitHandler(path, null, localPath);
+        let commits = 0;
+
+        await expect(
+          submit(
+            {
+              name: "",
+              baseURL: "https://chatgpt.com/backend-api",
+              apiKey: "",
+              model: "gpt-5",
+              oauthProfile: "work",
+            },
+            noopSetPhase,
+            {
+              skipValidation: false,
+              oauth: stagedCodexOAuth(async () => {
+                commits += 1;
+              }),
+            },
+          ),
+        ).rejects.toThrow(/reconnect codex/i);
+
+        expect(commits).toBe(0);
+        expect(await loadSettings(path)).toBeNull();
+        expect(await loadLocalSettings(localPath)).toBeNull();
+      });
+    });
+
     test("failed same-name reauthorization preserves the exact durable profile", async () => {
       await withTempDir(async (dir) => {
-        scopeCheckResult = { status: "insufficient-scope", message: "Reconnect Codex." };
+        scopeCheckResult = { status: "blocked", message: "Reconnect Codex." };
         const oldProfile = {
           name: "work",
           tokens: { access: "old-access", refresh: "old-refresh", expiresAt: 500 },
@@ -457,7 +492,7 @@ describe("buildProviderSubmitHandler", () => {
 
     test("explicit save-anyway skips the scope probe and commits exactly once", async () => {
       await withTempDir(async (dir) => {
-        scopeCheckResult = { status: "insufficient-scope", message: "should never be thrown" };
+        scopeCheckResult = { status: "blocked", message: "should never be thrown" };
         const localPath = localSettingsPath(dir);
         const submit = buildProviderSubmitHandler(join(dir, "settings.json"), null, localPath);
         let commits = 0;

src/tui/provider-setup-submit.ts

@@ -1,4 +1,8 @@
-import { checkOAuthProviderScope } from "../auth/oauth-scope-check.js";
+import {
+  OAuthProviderScopeError,
+  checkOAuthProviderScope,
+  isBlockingOAuthScopeCheckResult,
+} from "../auth/oauth-scope-check.js";
 import {
   mergeProviderIntoSettings,
   saveGlobalSettings,
@@ -48,28 +52,16 @@ export function buildProviderSubmitHandler(
     const trimmedKey = apiKey.trim();
     const selectedModel = model.trim();
 
-    // A signed-in subscription provider has no key to test or store in
-    // settings. Its exchanged credentials remain staged until this path has
-    // authorized persistence; once committed to the home-level auth store,
-    // config load projects that store into the provider catalog. Persist only
-    // non-secret provider/model metadata globally so the selection survives
-    // when a local settings target would alias this file.
-    //
-    // Unlike a pasted key, this credential was just issued by the real
-    // provider's own OAuth server completing a PKCE round-trip — so the
-    // token is real. That still doesn't confirm it carries usable API scope
-    // (vs. e.g. a chat-only subscription), which would otherwise surface as
-    // a confusing first-send auth error with no setup-attributable hint.
-    // Probe the provider's own catalog endpoint with the issued token before
-    // treating onboarding as complete: a definitive scope rejection blocks
-    // the submit with an actionable message (mirrors the API-key path's
-    // connection test); a check that could not run at all (network blip,
-    // timeout, rate limit) never blocks — only a proven scope failure does.
+    // OAuth credentials stay staged until setup validation authorizes durable
+    // persistence. Definitive API-scope or credential failures block the save;
+    // inconclusive probe failures do not. Once committed to the home-level auth
+    // store, config load projects it into the provider catalog, so only
+    // non-secret provider/model metadata is persisted globally.
     if (oauth !== undefined) {
       if (!skipValidation) {
         const scopeCheck = await checkOAuthProviderScope(oauth.kind, oauth.tokens);
-        if (scopeCheck.status === "insufficient-scope") {
-          throw new Error(scopeCheck.message);
+        if (isBlockingOAuthScopeCheckResult(scopeCheck)) {
+          throw new OAuthProviderScopeError(scopeCheck.message);
         }
       }
       setPhase("saving");