fix: improve Instagram OAuth2 token refresh flow

Author: YueTwo

backend/aci/server/oauth2_manager.py

@@ -3,11 +3,13 @@
 import time
 from typing import Any, cast
 
+import httpx
 from authlib.integrations.httpx_client import AsyncOAuth2Client
 
 from aci.common.exceptions import OAuth2Error
 from aci.common.logging_setup import get_logger
 from aci.common.schemas.security_scheme import OAuth2SchemeCredentials
+from aci.server import config
 
 UNICODE_ASCII_CHARACTER_SET = string.ascii_letters + string.digits
 logger = get_logger(__name__)
@@ -214,6 +216,16 @@ async def refresh_token(
         access_token: str,
         refresh_token: str,
     ) -> dict[str, Any]:
+        """
+        Refresh OAuth2 access token
+
+        Args:
+            access_token: The current access token used for Instagram refresh
+            refresh_token: The refresh token used for standard OAuth2 refresh
+
+        Returns:
+            Token response dictionary
+        """
         try:
             if self.app_name == "INSTAGRAM":
                 response = await self.oauth2_client.get(
@@ -233,11 +245,22 @@ async def refresh_token(
                         self.refresh_token_url, refresh_token=refresh_token
                     ),
                 )
-            return token
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to refresh access token, app_name={self.app_name}, error={e}")
+            if self.app_name == "INSTAGRAM" and e.response.status_code == 400:
+                raise OAuth2Error(
+                    f"Access token expired. Please re-authorize at: "
+                    f"{config.DEV_PORTAL_URL}/appconfigs/{self.app_name}"
+                ) from e
+            raise OAuth2Error("Failed to refresh access token") from e
+
         except Exception as e:
             logger.error(f"Failed to refresh access token, app_name={self.app_name}, error={e}")
             raise OAuth2Error("Failed to refresh access token") from e
 
+        return token
+
     async def parse_fetch_token_response(self, token: dict) -> OAuth2SchemeCredentials:
         """
         Parse OAuth2SchemeCredentials from token response with app-specific handling.

backend/aci/server/security_credentials_manager.py

@@ -97,17 +97,20 @@ async def _get_oauth2_credentials(
         linked_account.security_credentials
     )
     if _access_token_is_expired(oauth2_scheme_credentials):
-        # Instagram's access token only could be refreshed with a valid access token, so we need to re-authorize
+        # Instagram's access token only could be refreshed with a valid access token, so we need to re-authorize if invalid
         if app.name == "INSTAGRAM":
-            logger.error(
-                f"Access token expired, please re-authorize, linked_account_id={linked_account.id}, "
-                f"security_scheme={linked_account.security_scheme}, app={app.name}"
-            )
-            # NOTE: this error message could be used by the frontend to guide the user to re-authorize
-            raise OAuth2Error(
-                f"Access token expired. Please re-authorize at: "
-                f"{config.DEV_PORTAL_URL}/appconfigs/{app.name}"
-            )
+            # Since _access_token_is_expired returned True, expires_at is guaranteed to be not None
+            actual_expires_at = oauth2_scheme_credentials.expires_at + 86400  # type: ignore[operator]
+            if int(time.time()) > actual_expires_at:
+                logger.error(
+                    f"Access token expired, please re-authorize, linked_account_id={linked_account.id}, "
+                    f"security_scheme={linked_account.security_scheme}, app={app.name}"
+                )
+                # NOTE: this error message could be used by the frontend to guide the user to re-authorize
+                raise OAuth2Error(
+                    f"Access token expired. Please re-authorize at: "
+                    f"{config.DEV_PORTAL_URL}/appconfigs/{app.name}"
+                )
 
         logger.warning(
             f"Access token expired, trying to refresh linked_account_id={linked_account.id}, "
@@ -116,6 +119,7 @@ async def _get_oauth2_credentials(
         token_response = await _refresh_oauth2_access_token(
             app.name, oauth2_scheme, oauth2_scheme_credentials
         )
+
         # TODO: refactor parsing to _refresh_oauth2_access_token
         expires_at: int | None = None
         if "expires_at" in token_response: