Retry OAuth refreshes

Author: N2D4

.claude/CLAUDE-KNOWLEDGE.md

@@ -217,6 +217,9 @@ A: Check the error location:
 - Callback endpoint (400 error) - Validation failed during callback
 - Token endpoint (400 error) - Validation failed during token exchange
 
+### Q: How should connected-account OAuth access-token refresh errors be classified?
+A: In `apps/backend/src/oauth/providers/base.tsx`, invalid/revoked refresh-token provider errors such as `invalid_grant` return `Result.error({ type: "invalid-refresh-token", ... })` so `access-token-helpers.tsx` can invalidate that stored refresh token and try another. Transient provider/network failures such as openid-client `RPError: outgoing request timed out after 3500ms` return `Result.error({ type: "temporarily-unavailable", cause })`; the connected-account helper converts that to `OAuthProviderTemporarilyUnavailable` without invalidating the refresh token. Expected refresh outcomes should be represented in the provider return type instead of thrown as known/status errors. Refresh requests use a 6s openid-client HTTP timeout and retry transient failures once. If a retry sees `invalid_grant` after an ambiguous transient failure, keep treating it as temporarily unavailable rather than invalidating the refresh token, because the first request may have reached the provider and rotated the token before our client timed out. Sentry should capture non-revocation refresh issues (temporary provider failure, invalid client, unexpected) with provider id/class, attempts, retry count, ambiguity state, final cause, and all provider errors seen during attempts; normal revoked/expired refresh tokens should not be reported.
+
 ## Git and Development Workflow
 
 ### Q: How should you format git commit messages in this project?

apps/backend/src/app/api/latest/connected-accounts/access-token-helpers.tsx

@@ -1,11 +1,37 @@
-import { OAuthBaseProvider, TokenSet } from "@/oauth/providers/base";
+import { OAuthBaseProvider } from "@/oauth/providers/base";
+import type { OAuthAccessTokenRefreshError } from "@/oauth/providers/base";
 import { getPrismaClientForTenancy } from "@/prisma-client";
 import { KnownErrors } from "@stackframe/stack-shared";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
-import { StackAssertionError, captureError } from "@stackframe/stack-shared/dist/utils/errors";
-import { Result } from "@stackframe/stack-shared/dist/utils/results";
+import { StackAssertionError, StatusError, captureError } from "@stackframe/stack-shared/dist/utils/errors";
 import { extractScopes } from "@stackframe/stack-shared/dist/utils/strings";
 
+function captureOAuthAccessTokenRefreshIssue(options: {
+  location: string,
+  message: string,
+  providerInstance: OAuthBaseProvider,
+  errorContext: Record<string, unknown>,
+  refreshError: Exclude<OAuthAccessTokenRefreshError, { type: "invalid-refresh-token" }>,
+}) {
+  const providerId = typeof options.errorContext.providerId === "string" ? options.errorContext.providerId : "unknown";
+  const providerClass = options.providerInstance.constructor.name;
+  captureError(options.location, new StackAssertionError(
+    `${options.message} (providerId: ${providerId}, providerClass: ${providerClass}, attempts: ${options.refreshError.attempts}, retries: ${options.refreshError.retryCount})`,
+    {
+      cause: options.refreshError.cause,
+      ...options.errorContext,
+      providerId,
+      providerClass,
+      refreshErrorType: options.refreshError.type,
+      attempts: options.refreshError.attempts,
+      retryCount: options.refreshError.retryCount,
+      sawAmbiguousRefreshAttempt: options.refreshError.sawAmbiguousRefreshAttempt,
+      error: options.refreshError.cause,
+      causes: options.refreshError.causes,
+    },
+  ));
+}
+
 /**
  * Access tokens minted under Stack Auth's shared OAuth apps must not be handed
  * to clients — they carry Stack Auth's brand at the provider. Only allowed when
@@ -122,27 +148,71 @@ export async function retrieveOrRefreshAccessToken(options: {
   }
 
   for (const token of filteredRefreshTokens) {
-    let tokenSetResult: Result<TokenSet, string>;
-    try {
-      tokenSetResult = await providerInstance.getAccessToken({
-        refreshToken: token.refreshToken,
-        scope,
-      });
-    } catch (error) {
-      captureError('oauth-access-token-refresh-unexpected-error', new StackAssertionError('Unexpected error refreshing access token — this may indicate a bug or misconfiguration', {
-        error,
-        ...errorContext,
-      }));
-
-      tokenSetResult = Result.error("Unexpected error refreshing access token");
-    }
+    const tokenSetResult = await providerInstance.getAccessToken({
+      refreshToken: token.refreshToken,
+      scope,
+    });
 
     if (tokenSetResult.status === "error") {
-      await prisma.oAuthToken.update({
-        where: { id: token.id },
-        data: { isValid: false },
-      });
-      continue;
+      switch (tokenSetResult.error.type) {
+        case "invalid-refresh-token": {
+          // Only this outcome proves that the stored refresh token should no
+          // longer be used. Provider timeouts and retry ambiguity must not
+          // invalidate the connection; the user usually cannot fix those.
+          await prisma.oAuthToken.update({
+            where: { id: token.id },
+            data: { isValid: false },
+          });
+          continue;
+        }
+        case "temporarily-unavailable": {
+          // The customer should retry later. Do not mark the OAuth connection as
+          // broken or ask the user to reconnect based on a transient provider
+          // failure.
+          captureOAuthAccessTokenRefreshIssue({
+            location: "oauth-access-token-refresh-provider-temporarily-unavailable",
+            message: "OAuth provider temporarily unavailable during access token refresh",
+            providerInstance,
+            errorContext,
+            refreshError: tokenSetResult.error,
+          });
+          throw new KnownErrors.OAuthProviderTemporarilyUnavailable();
+        }
+        case "invalid-client": {
+          captureOAuthAccessTokenRefreshIssue({
+            location: "oauth-access-token-refresh-invalid-client",
+            message: "OAuth provider rejected configured client during access token refresh",
+            providerInstance,
+            errorContext,
+            refreshError: tokenSetResult.error,
+          });
+          throw new StatusError(400, `Invalid client credentials for this OAuth provider. Please ensure the configuration in the Stack Auth dashboard is correct.`);
+        }
+        case "unexpected": {
+          captureOAuthAccessTokenRefreshIssue({
+            location: "oauth-access-token-refresh-unexpected-error",
+            message: "Unexpected OAuth provider error during access token refresh",
+            providerInstance,
+            errorContext,
+            refreshError: tokenSetResult.error,
+          });
+          const assertionError = new StackAssertionError('Unexpected error refreshing access token — this may indicate a bug or misconfiguration', {
+            error: tokenSetResult.error.cause,
+            providerClass: providerInstance.constructor.name,
+            refreshErrorType: tokenSetResult.error.type,
+            attempts: tokenSetResult.error.attempts,
+            retryCount: tokenSetResult.error.retryCount,
+            sawAmbiguousRefreshAttempt: tokenSetResult.error.sawAmbiguousRefreshAttempt,
+            causes: tokenSetResult.error.causes,
+            ...errorContext,
+          });
+          throw assertionError;
+        }
+        default: {
+          const _: never = tokenSetResult.error;
+          throw new StackAssertionError("Unhandled OAuth access token refresh error", { error: _ });
+        }
+      }
     }
 
     const tokenSet = tokenSetResult.data;

apps/backend/src/oauth/providers/base.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { isRetryableOAuthUserInfoError } from "./base";
+import { getOAuthAccessTokenRefreshError, getOAuthAccessTokenRefreshErrorDisposition, isRetryableOAuthUserInfoError } from "./base";
 
 describe("isRetryableOAuthUserInfoError", () => {
   it("returns true for openid-client timeout errors", () => {
@@ -52,3 +52,52 @@ describe("isRetryableOAuthUserInfoError", () => {
     })).toBe(true);
   });
 });
+
+describe("getOAuthAccessTokenRefreshErrorDisposition", () => {
+  it("treats openid-client refresh timeouts as temporarily unavailable", () => {
+    expect(getOAuthAccessTokenRefreshErrorDisposition({
+      name: "RPError",
+      message: "outgoing request timed out after 3500ms",
+    })).toEqual({ type: "temporarily-unavailable" });
+  });
+
+  it("treats invalid_grant refresh failures as invalid refresh tokens", () => {
+    expect(getOAuthAccessTokenRefreshErrorDisposition({
+      error: "invalid_grant",
+    })).toEqual({
+      type: "invalid-refresh-token",
+      message: "Refresh token is invalid or expired",
+    });
+  });
+
+  it("recognizes nested OAuth provider error codes", () => {
+    expect(getOAuthAccessTokenRefreshErrorDisposition({
+      error: {
+        error: "invalid_grant",
+      },
+    })).toEqual({
+      type: "invalid-refresh-token",
+      message: "Refresh token is invalid or expired",
+    });
+  });
+});
+
+describe("getOAuthAccessTokenRefreshError", () => {
+  it("does not treat invalid_grant after an ambiguous refresh attempt as a revoked token", () => {
+    const providerError = {
+      error: "invalid_grant",
+    };
+    expect(getOAuthAccessTokenRefreshError(providerError, {
+      sawAmbiguousRefreshAttempt: true,
+      attempts: 2,
+      causes: [{ name: "RPError" }, providerError],
+    })).toEqual({
+      type: "temporarily-unavailable",
+      cause: providerError,
+      attempts: 2,
+      retryCount: 1,
+      sawAmbiguousRefreshAttempt: true,
+      causes: [{ name: "RPError" }, providerError],
+    });
+  });
+});