feat: return explicit refresh-token invalid error for OAuth refresh failures (#4751)

## Bug
When a konnector calls POST /accounts/:accountType/:accountID/refresh,
stack refreshes OAuth token with provider.
If provider rejects refresh token, stack currently returns a generic
internal error.
Connector cannot reliably detect “refresh token is invalid, user must
reconnect account”, so it often falls back to generic VENDOR_DOWN.

This hides the real problem for users and support. And doesn't allow
users to reinitialize the refresh token manually

  ## What changed

  - Added typed refresh error classification in account refresh flow.
- On provider OAuth errors invalid_token or invalid_grant, stack now
classifies as:
      - code: oauth_refresh_invalid_token
- In /accounts/:accountType/:accountID/refresh, this classified error is
returned as JSON:API:
      - status 401
      - code oauth_refresh_invalid_token
      - detail: reconnect needed message
  - Kept other refresh failures on generic error path.

Author: shepilov

docs/konnectors-workflow.md

@@ -644,6 +644,25 @@ POST /accounts/:accountType/:accountID/refresh HTTP/1.1
 Host: bob.cozy.rocks
 ```
 
+If the OAuth provider rejects the refresh token, the stack returns a structured
+JSON:API error that can be mapped to a reconnect flow:
+
+```http
+HTTP/1.1 401 Unauthorized
+Content-Type: application/vnd.api+json
+
+{
+  "errors": [
+    {
+      "status": "401",
+      "title": "Unauthorized",
+      "code": "oauth_refresh_invalid_token",
+      "detail": "OAuth refresh token is invalid or expired; reconnect account."
+    }
+  ]
+}
+```
+
 ### Konnectors Marketplace Requirements
 
 The following is a few points to be careful for in konnectors when we start

model/account/type.go

@@ -65,6 +65,56 @@ var RefreshToken = "refresh_token"
 // within an account does not allow refreshing it.
 var ErrUnrefreshable = errors.New("this account can not be refreshed")
 
+const (
+	// RefreshOAuthErrorCodeInvalidToken indicates the refresh token has been
+	// rejected by the OAuth provider and the account should be reconnected.
+	RefreshOAuthErrorCodeInvalidToken = "oauth_refresh_invalid_token"
+)
+
+// RefreshOAuthError represents a classified OAuth refresh failure.
+type RefreshOAuthError struct {
+	Code           string
+	ProviderStatus int
+	ProviderError  string
+}
+
+func (e *RefreshOAuthError) Error() string {
+	if e == nil {
+		return "oauth refresh failed"
+	}
+	msg := "oauth refresh failed"
+	if e.Code != "" {
+		msg += ": " + e.Code
+	}
+	if e.ProviderStatus != 0 {
+		msg += fmt.Sprintf(" (status %d)", e.ProviderStatus)
+	}
+	if e.ProviderError != "" {
+		msg += ", provider_error=" + e.ProviderError
+	}
+	return msg
+}
+
+// IsRefreshOAuthErrorCode checks if err is a refresh error with the given code.
+func IsRefreshOAuthErrorCode(err error, code string) bool {
+	var refreshErr *RefreshOAuthError
+	if !errors.As(err, &refreshErr) {
+		return false
+	}
+	return refreshErr.Code == code
+}
+
+func isInvalidRefreshTokenError(out tokenEndpointResponse) bool {
+	switch out.Error {
+	case "invalid_token":
+		return true
+	case "invalid_grant":
+		return true
+	default:
+		return false
+	}
+}
+
 // AccountType holds configuration information for
 type AccountType struct {
 	DocID  string `json:"_id,omitempty"`
@@ -417,8 +467,38 @@ func (at *AccountType) RefreshAccount(a Account) error {
 	}
 
 	if res.StatusCode != 200 {
-		log.Errorf("Account %s: OAuth service error (status %d): %s", a.ID(), res.StatusCode, string(resBody))
-		return fmt.Errorf("oauth service responded with status %d: %s", res.StatusCode, string(resBody))
+		var out tokenEndpointResponse
+		if err = json.Unmarshal(resBody, &out); err != nil {
+			log.Errorf(
+				"Account %s: OAuth service error (status %d): non-JSON response: %s (body=%s)",
+				a.ID(),
+				res.StatusCode,
+				err,
+				string(resBody),
+			)
+			return fmt.Errorf("oauth service responded with status %d", res.StatusCode)
+		}
+
+		if isInvalidRefreshTokenError(out) {
+			log.Errorf(
+				"Account %s: OAuth refresh token rejected by provider (status %d, error=%s)",
+				a.ID(),
+				res.StatusCode,
+				out.Error,
+			)
+			return &RefreshOAuthError{
+				Code:           RefreshOAuthErrorCodeInvalidToken,
+				ProviderStatus: res.StatusCode,
+				ProviderError:  out.Error,
+			}
+		}
+
+		if out.Error != "" {
+			log.Errorf("Account %s: OAuth service error (status %d, error=%s)", a.ID(), res.StatusCode, out.Error)
+		} else {
+			log.Errorf("Account %s: OAuth service error (status %d)", a.ID(), res.StatusCode)
+		}
+		return fmt.Errorf("oauth service responded with status %d", res.StatusCode)
 	}
 
 	var out tokenEndpointResponse

web/accounts/oauth.go

@@ -32,6 +32,18 @@ func (a *apiAccount) Links() *jsonapi.LinksList {
 	return &jsonapi.LinksList{Self: "/data/" + consts.Accounts + "/" + a.ID()}
 }
 
+func mapRefreshError(err error) error {
+	if account.IsRefreshOAuthErrorCode(err, account.RefreshOAuthErrorCodeInvalidToken) {
+		return &jsonapi.Error{
+			Status: http.StatusUnauthorized,
+			Title:  "Unauthorized",
+			Code:   account.RefreshOAuthErrorCodeInvalidToken,
+			Detail: "OAuth refresh token is invalid or expired; reconnect account.",
+		}
+	}
+	return err
+}
+
 func start(c echo.Context) error {
 	instance := middlewares.GetInstance(c)
 
@@ -231,7 +243,7 @@ func refresh(c echo.Context) error {
 
 	err = accountType.RefreshAccount(acc)
 	if err != nil {
-		return err
+		return mapRefreshError(err)
 	}
 
 	err = couchdb.UpdateDoc(instance, &acc)

web/accounts/oauth_test.go

@@ -17,6 +17,7 @@ import (
 	"github.com/cozy/cozy-stack/pkg/couchdb"
 	"github.com/cozy/cozy-stack/pkg/prefixer"
 	"github.com/cozy/cozy-stack/tests/testutils"
+	weberrors "github.com/cozy/cozy-stack/web/errors"
 	"github.com/gavv/httpexpect/v2"
 	"github.com/labstack/echo/v4"
 	"github.com/stretchr/testify/assert"
@@ -36,6 +37,7 @@ func TestOauth(t *testing.T) {
 
 	setup := testutils.NewSetup(t, t.Name())
 	ts := setup.GetTestServer("/accounts", Routes, func(r *echo.Echo) *echo.Echo {
+		r.HTTPErrorHandler = weberrors.ErrorHandler
 		r.POST("/login", func(c echo.Context) error {
 			sess, _ := session.New(testInstance, session.LongRun, "")
 			cookie, _ := sess.ToCookie()
@@ -330,6 +332,58 @@ func TestOauth(t *testing.T) {
 		res.Cookies().Length().Equal(1)
 		res.Cookie("cozysessid").Value().NotEmpty()
 	})
+
+	t.Run("RefreshReturnsStructuredInvalidTokenError", func(t *testing.T) {
+		e := testutils.CreateTestClient(t, ts.URL)
+		_, token := setup.GetTestClient(consts.Accounts)
+
+		service := httptest.NewServer(http.HandlerFunc(func(c http.ResponseWriter, r *http.Request) {
+			require.Equal(t, http.MethodPost, r.Method)
+			require.NoError(t, r.ParseForm())
+			assert.Equal(t, "refresh_token", r.FormValue("grant_type"))
+			assert.Equal(t, "bad-refresh-token", r.FormValue("refresh_token"))
+			assert.Equal(t, "the-client-id", r.FormValue("client_id"))
+			assert.Equal(t, "the-client-secret", r.FormValue("client_secret"))
+			c.Header().Set("Content-Type", "application/json")
+			c.WriteHeader(http.StatusUnauthorized)
+			_, _ = c.Write([]byte(`{"error":"invalid_token","error_description":"refresh token rejected"}`))
+		}))
+		t.Cleanup(service.Close)
+
+		serviceType := account.AccountType{
+			DocID:         "test-service-refresh",
+			TokenEndpoint: service.URL + "/oauth2/token",
+			ClientID:      "the-client-id",
+			ClientSecret:  "the-client-secret",
+		}
+		err := couchdb.CreateNamedDoc(prefixer.SecretsPrefixer, &serviceType)
+		require.NoError(t, err)
+		t.Cleanup(func() { _ = couchdb.DeleteDoc(prefixer.SecretsPrefixer, &serviceType) })
+
+		acc := &account.Account{
+			AccountType: serviceType.DocID,
+			Oauth: &account.OauthInfo{
+				RefreshToken: "bad-refresh-token",
+			},
+		}
+		require.NoError(t, couchdb.CreateDoc(testInstance, acc))
+		t.Cleanup(func() {
+			acc.ManualCleaning = true
+			_ = couchdb.DeleteDoc(testInstance, acc)
+		})
+
+		obj := e.POST("/accounts/test-service-refresh/"+acc.ID()+"/refresh").
+			WithHeader("Authorization", "Bearer "+token).
+			Expect().Status(http.StatusUnauthorized).
+			JSON(httpexpect.ContentOpts{MediaType: "application/vnd.api+json"}).
+			Object()
+
+		errObj := obj.Value("errors").Array().First().Object()
+		errObj.ValueEqual("status", "401")
+		errObj.ValueEqual("title", "Unauthorized")
+		errObj.ValueEqual("code", account.RefreshOAuthErrorCodeInvalidToken)
+		errObj.ValueEqual("detail", "OAuth refresh token is invalid or expired; reconnect account.")
+	})
 }
 
 func makeTestRedirectURLService(redirectURI string) *httptest.Server {