Skip to content

Self-improving AI Employees for everyone

refactor(oauth): OAuth2PKCEClient base + lifecycle factories + Twitter migration (Wave 11.I, S.1)

trohitg9a2ab7bf6355
diff --git a/server/nodes/twitter/_handlers.py b/server/nodes/twitter/_handlers.py
index bae85323..54888506 100644
--- a/server/nodes/twitter/_handlers.py
+++ b/server/nodes/twitter/_handlers.py
@@ -1,179 +1,77 @@
-"""Twitter / X WebSocket handlers — plugin-owned dispatch table.
-
-OAuth 2.0 PKCE login + status + logout flows. Self-registered into
-the central WS dispatcher via ``register_ws_handlers(WS_HANDLERS)``
-from this package's ``__init__.py``. ``routers/websocket.py`` knows
-nothing about Twitter; the message-type strings are wired here so
-renames / additions stay local to the plugin.
-
-Companion: ``_router.py`` owns the OAuth callback endpoint
-(``/api/twitter/callback``) — same redirect URI the WS login flow
-asks the user to visit. Both share the same ``TwitterOAuth`` client
-in ``_oauth.py``.
+"""Twitter / X WebSocket handlers — factory-built (Wave 11.I, S).
+
+The 3 handlers (``twitter_oauth_login`` / ``twitter_oauth_status`` /
+``twitter_logout``) come from
+:func:`services.events.oauth_lifecycle.make_oauth_lifecycle_handlers`.
+The factory takes care of credential loading, redirect-URI derivation,
+silent token refresh on status, revoke + remove + broadcast on
+logout. Plugin-specific bits supplied via kwargs:
+
+* ``oauth_factory`` -- async builder that constructs
+ :class:`TwitterOAuth` per call, pulling stored client_id /
+ client_secret from ``auth_service``.
+* ``user_info_to_subject`` -- ``f"@{username}"`` (X has no email).
+* ``extra_logout`` -- drops legacy API-key entries left behind by the
+ pre-OAuth layout.
"""
from __future__ import annotations
-from typing import Any, Dict
+from typing import Any, Dict, Optional
-from fastapi import WebSocket
-
-from core.logging import get_logger
-from services.oauth_utils import get_redirect_uri
-from services.status_broadcaster import get_status_broadcaster
+from services.events.oauth_lifecycle import make_oauth_lifecycle_handlers
from ._oauth import TwitterOAuth
-logger = get_logger(__name__)
-
-async def handle_twitter_oauth_login(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """Initiate Twitter OAuth 2.0 with PKCE flow.
-
- Opens the browser to Twitter's authorization page. After the user
- authorises, Twitter redirects to ``/api/twitter/callback`` (owned
- by ``_router.py``) which stores tokens via ``auth_service``.
- """
- # Lazy ``container`` import — same idiom the original handler used
- # in ``routers/websocket.py``. Keeps test monkeypatching simple
- # (the singleton lookup happens at call time, post-patch).
+async def _twitter_oauth_factory(
+ *, redirect_uri: Optional[str] = None, **_kwargs,
+) -> TwitterOAuth:
+ """Build a :class:`TwitterOAuth` from stored client credentials."""
from core.container import container
auth_service = container.auth_service()
-
- # Stored client credentials (configured via Credentials Modal).
- client_id = await auth_service.get_api_key("twitter_client_id")
+ client_id = await auth_service.get_api_key("twitter_client_id") or ""
client_secret = await auth_service.get_api_key("twitter_client_secret")
+ return TwitterOAuth(
+ client_id=client_id,
+ client_secret=client_secret,
+ redirect_uri=redirect_uri or "",
+ )
- if not client_id:
- return {
- "success": False,
- "error": "Twitter Client ID not configured. Add your Twitter API credentials first.",
- }
-
- redirect_uri = get_redirect_uri(websocket, "twitter")
- oauth = TwitterOAuth(client_id=client_id, client_secret=client_secret, redirect_uri=redirect_uri)
- auth_data = oauth.generate_authorization_url()
- return {
- "success": True,
- "message": "Opening Twitter authorization in browser...",
- "url": auth_data["url"],
- "state": auth_data["state"],
- }
+def _user_info_to_handle(info: Dict[str, Any]) -> str:
+ return f"@{info.get('username', 'unknown')}"
-async def handle_twitter_oauth_status(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """Check Twitter OAuth connection status.
+async def _drop_legacy_api_key_entries() -> None:
+ """Remove stale API-key entries from the pre-OAuth layout.
- Returns connection status + user info if connected. Tokens live in
- the OAuth system (``EncryptedOAuthToken`` table); never read via
- ``get_api_key("twitter_access_token")`` — that's the wrong table.
- Refreshes silently if the access token is rejected and a refresh
- token exists.
+ Pre-Wave-11.I some flows mistakenly stored access / refresh tokens
+ as API keys. The OAuth tokens table is the canonical home now;
+ these orphans are cleaned on every logout for safety.
"""
from core.container import container
auth_service = container.auth_service()
-
- tokens = await auth_service.get_oauth_tokens("twitter", customer_id="owner")
- if not tokens or not tokens.get("access_token"):
- return {"connected": False, "username": None, "user_id": None}
-
- access_token = tokens["access_token"]
- refresh_token = tokens.get("refresh_token", "")
- client_id = await auth_service.get_api_key("twitter_client_id") or ""
- client_secret = await auth_service.get_api_key("twitter_client_secret")
- redirect_uri = get_redirect_uri(websocket, "twitter")
-
- oauth = TwitterOAuth(client_id=client_id, client_secret=client_secret, redirect_uri=redirect_uri)
- user_info = await oauth.get_user_info(access_token)
-
- if not user_info.get("success") and refresh_token:
- refresh_result = await oauth.refresh_access_token(refresh_token)
- if refresh_result.get("success"):
- await auth_service.store_oauth_tokens(
- provider="twitter",
- access_token=refresh_result["access_token"],
- refresh_token=refresh_result.get("refresh_token") or refresh_token,
- email=tokens.get("email", ""),
- name=tokens.get("name", ""),
- scopes=tokens.get("scopes", ""),
- customer_id="owner",
- )
- user_info = await oauth.get_user_info(refresh_result["access_token"])
-
- if not user_info.get("success"):
- return {
- "connected": False,
- "username": None,
- "user_id": None,
- "error": user_info.get("error"),
- }
-
- return {
- "connected": True,
- "username": user_info.get("username"),
- "user_id": user_info.get("id"),
- "name": user_info.get("name"),
- "profile_image_url": user_info.get("profile_image_url"),
- "verified": user_info.get("verified"),
- }
-
-
-async def handle_twitter_logout(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """Disconnect Twitter: revoke tokens + clear stored credentials.
-
- Per RFC 9700 the refresh-token is read directly from the DB
- (``get_oauth_refresh_token``) instead of from the in-memory cache.
- Symmetric ``credential.oauth.disconnected`` broadcast fires the
- catalogue refetch on every connected client.
- """
- from core.container import container
-
- auth_service = container.auth_service()
-
- tokens = await auth_service.get_oauth_tokens("twitter", customer_id="owner")
- access_token = tokens.get("access_token") if tokens else None
- refresh_token = (
- await auth_service.get_oauth_refresh_token("twitter", customer_id="owner")
- if tokens
- else None
- )
-
- client_id = await auth_service.get_api_key("twitter_client_id") or ""
- client_secret = await auth_service.get_api_key("twitter_client_secret")
-
- if access_token or refresh_token:
- redirect_uri = get_redirect_uri(websocket, "twitter")
- oauth = TwitterOAuth(client_id=client_id, client_secret=client_secret, redirect_uri=redirect_uri)
- if access_token:
- await oauth.revoke_token(access_token, "access_token")
- if refresh_token:
- await oauth.revoke_token(refresh_token, "refresh_token")
-
- await auth_service.remove_oauth_tokens("twitter", customer_id="owner")
-
- # Clean up any stale API-key entries from the old (broken) layout
- # where access tokens were mistakenly stored as API keys.
for key in ("twitter_access_token", "twitter_refresh_token", "twitter_user_info"):
try:
await auth_service.remove_api_key(key)
except Exception:
pass
- broadcaster = get_status_broadcaster()
- await broadcaster.broadcast_credential_event(
- "credential.oauth.disconnected",
- provider="twitter",
- customer_id="owner",
- )
-
- return {"success": True, "message": "Twitter disconnected"}
-
-WS_HANDLERS = {
- "twitter_oauth_login": handle_twitter_oauth_login,
- "twitter_oauth_status": handle_twitter_oauth_status,
- "twitter_logout": handle_twitter_logout,
-}
+WS_HANDLERS = make_oauth_lifecycle_handlers(
+ provider="twitter",
+ oauth_factory=_twitter_oauth_factory,
+ user_info_to_subject=_user_info_to_handle,
+ extra_logout=_drop_legacy_api_key_entries,
+)
+
+# Module-level aliases so the contract tests in
+# ``tests/credentials/test_websocket_handlers.py`` can import the
+# handlers by name. The dispatch table itself is what
+# ``register_ws_handlers`` consumes.
+handle_twitter_oauth_login = WS_HANDLERS["twitter_oauth_login"]
+handle_twitter_oauth_status = WS_HANDLERS["twitter_oauth_status"]
+handle_twitter_logout = WS_HANDLERS["twitter_logout"]
diff --git a/server/nodes/twitter/_oauth.py b/server/nodes/twitter/_oauth.py
index 9af0536c..3275900c 100644
--- a/server/nodes/twitter/_oauth.py
+++ b/server/nodes/twitter/_oauth.py
@@ -1,411 +1,124 @@
-"""
-Twitter/X OAuth 2.0 with PKCE - Browser-based login flow for X API v2.
+"""Twitter / X OAuth 2.0 PKCE client.
-Based on official X API documentation:
-- Authorization URL: https://x.com/i/oauth2/authorize
-- Token URL: https://api.x.com/2/oauth2/token
-- Docs: https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code
+Wave 11.I, milestone S: subclasses :class:`OAuth2PKCEClient` from
+:mod:`services.plugin.oauth`. The base class owns the PKCE state
+store, code-verifier generation, code exchange, token refresh, and
+revocation. This file declares X-specific endpoints + scopes +
+``fetch_user_info`` translation.
-Access tokens expire in 2 hours by default. Use offline.access scope for refresh tokens.
-Authorization codes expire in 30 seconds.
+Pre-S the file hand-rolled all of that (~410 LOC). The only Twitter-
+specific behaviour now lives in this small subclass.
"""
-import base64
-import hashlib
-import secrets
-import time
-from typing import Any, Dict, Optional
-from urllib.parse import urlencode
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
import httpx
from core.logging import get_logger
+from services.plugin.oauth import OAuth2PKCEClient, OAuthStateStore
logger = get_logger(__name__)
-# X API OAuth 2.0 endpoints (updated URLs per latest docs)
+# X API OAuth 2.0 endpoints. Updated URLs per latest docs. Public so
+# the contract tests in tests/credentials/test_twitter_oauth.py can
+# pin them via respx mocks.
AUTHORIZATION_URL = "https://x.com/i/oauth2/authorize"
TOKEN_URL = "https://api.x.com/2/oauth2/token"
REVOKE_URL = "https://api.x.com/2/oauth2/revoke"
USER_INFO_URL = "https://api.x.com/2/users/me"
-# Required scopes for full Twitter integration
+# Required scopes for full Twitter integration.
# See: https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code
-DEFAULT_SCOPES = [
- "tweet.read", # Read tweets
- "tweet.write", # Post tweets
- "users.read", # User lookup
- "follows.read", # Read followers/following
- "like.read", # Read likes
- "like.write", # Like/unlike tweets
- "offline.access", # Enable refresh tokens (access tokens expire in 2 hours)
+_DEFAULT_SCOPES = [
+ "tweet.read",
+ "tweet.write",
+ "users.read",
+ "follows.read",
+ "like.read",
+ "like.write",
+ "offline.access", # enables refresh tokens
]
-# In-memory store for PKCE state (production should use Redis/database)
-_oauth_states: Dict[str, Dict[str, Any]] = {}
-
-
-def _generate_code_verifier() -> str:
- """
- Generate a cryptographically random code verifier (43-128 chars).
- Per RFC 7636, must be 43-128 characters from [A-Z, a-z, 0-9, -, ., _, ~].
- """
- # Generate 96 random bytes, encode to base64url (128 chars after stripping padding)
- random_bytes = secrets.token_bytes(96)
- verifier = base64.urlsafe_b64encode(random_bytes).rstrip(b"=").decode("ascii")
- return verifier[:128]
-
-
-def _generate_code_challenge(code_verifier: str) -> str:
- """
- Generate S256 code challenge from verifier.
- challenge = BASE64URL(SHA256(code_verifier))
- """
- digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
- challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
- return challenge
-
-
-def _generate_state() -> str:
- """Generate random state parameter for CSRF protection (up to 500 chars per X docs)."""
- return secrets.token_urlsafe(32)
-
-
-class TwitterOAuth:
- """
- Twitter/X OAuth 2.0 with PKCE flow implementation.
- Usage:
- oauth = TwitterOAuth(client_id="...", redirect_uri="http://localhost:3010/api/twitter/callback") # URI derived at runtime
+class TwitterOAuth(OAuth2PKCEClient):
+ """X (Twitter) OAuth 2.0 PKCE client."""
- # Step 1: Generate authorization URL
- auth_data = oauth.generate_authorization_url()
- # Redirect user to auth_data["url"]
+ provider = "twitter"
+ authorization_endpoint = AUTHORIZATION_URL
+ token_endpoint = TOKEN_URL
+ revocation_endpoint = REVOKE_URL
- # Step 2: Handle callback and exchange code
- tokens = await oauth.exchange_code(code="...", state="...")
+ # Plugin-scoped state store -- isolated from Google's instance.
+ state_store = OAuthStateStore()
- # Step 3: Use access_token for API calls
- user_info = await oauth.get_user_info(tokens["access_token"])
- """
+ DEFAULT_SCOPES = _DEFAULT_SCOPES
def __init__(
self,
client_id: str,
redirect_uri: str,
client_secret: Optional[str] = None,
- scopes: Optional[list] = None,
- ):
- """
- Initialize Twitter OAuth client.
-
- Args:
- client_id: Twitter OAuth 2.0 Client ID (from Developer Portal)
- client_secret: Client Secret (required for confidential clients, optional for public clients with PKCE)
- redirect_uri: OAuth callback URL (must match Developer Portal settings exactly)
- scopes: List of OAuth scopes (defaults to DEFAULT_SCOPES)
- """
- self.client_id = client_id
- self.client_secret = client_secret
- self.redirect_uri = redirect_uri
- self.scopes = scopes or DEFAULT_SCOPES
-
- def generate_authorization_url(self) -> Dict[str, str]:
- """
- Generate OAuth authorization URL with PKCE parameters.
-
- Returns:
- Dict with:
- - url: Authorization URL to redirect user to
- - state: State parameter (for verification in callback)
- - code_verifier: PKCE code verifier (save for token exchange)
- """
- state = _generate_state()
- code_verifier = _generate_code_verifier()
- code_challenge = _generate_code_challenge(code_verifier)
-
- # Store state for verification (with expiry tracking)
- _oauth_states[state] = {
- "code_verifier": code_verifier,
- "created_at": time.time(),
- "redirect_uri": self.redirect_uri,
- }
-
- params = {
- "response_type": "code",
- "client_id": self.client_id,
- "redirect_uri": self.redirect_uri,
- "scope": " ".join(self.scopes),
- "state": state,
- "code_challenge": code_challenge,
- "code_challenge_method": "S256",
- }
-
- authorization_url = f"{AUTHORIZATION_URL}?{urlencode(params)}"
-
- logger.info("Generated Twitter OAuth authorization URL", state=state[:8])
-
- return {
- "url": authorization_url,
- "state": state,
- "code_verifier": code_verifier,
- }
-
- async def exchange_code(self, code: str, state: str) -> Dict[str, Any]:
- """
- Exchange authorization code for access token.
-
- Note: Authorization codes expire in 30 seconds per X docs.
-
- Args:
- code: Authorization code from callback
- state: State parameter for verification
-
- Returns:
- Dict with:
- - success: True/False
- - access_token: Bearer token for API calls (expires in 2 hours)
- - refresh_token: Token for refreshing access (if offline.access scope)
- - expires_in: Token expiry in seconds
- - scope: Granted scopes
- """
- # Verify state and get code_verifier
- oauth_state = _oauth_states.pop(state, None)
- if not oauth_state:
- logger.error("Invalid or expired OAuth state", state=state[:8] if state else "None")
- return {"success": False, "error": "Invalid or expired state"}
-
- code_verifier = oauth_state["code_verifier"]
-
- # Prepare token request body
- data = {
- "grant_type": "authorization_code",
- "code": code,
- "redirect_uri": self.redirect_uri,
- "code_verifier": code_verifier,
- }
-
- # Authentication: Basic auth for confidential clients, client_id in body for public clients
- headers = {"Content-Type": "application/x-www-form-urlencoded"}
-
- if self.client_secret:
- # Confidential client: use Basic auth
- credentials = base64.b64encode(
- f"{self.client_id}:{self.client_secret}".encode()
- ).decode()
- headers["Authorization"] = f"Basic {credentials}"
- else:
- # Public client: include client_id in body
- data["client_id"] = self.client_id
-
- try:
- async with httpx.AsyncClient(timeout=30.0) as client:
- response = await client.post(
- TOKEN_URL,
- data=data,
- headers=headers,
- )
-
- if response.status_code != 200:
- error_data = response.json() if response.text else {}
- logger.error(
- "Token exchange failed",
- status=response.status_code,
- error=error_data,
- )
- return {
- "success": False,
- "error": error_data.get("error_description", error_data.get("error", "Token exchange failed")),
- }
-
- token_data = response.json()
- logger.info("Twitter OAuth token exchange successful")
-
- return {
- "success": True,
- "access_token": token_data.get("access_token"),
- "refresh_token": token_data.get("refresh_token"),
- "expires_in": token_data.get("expires_in"),
- "scope": token_data.get("scope"),
- "token_type": token_data.get("token_type", "Bearer"),
- }
-
- except httpx.HTTPError as e:
- logger.error("HTTP error during token exchange", error=str(e))
- return {"success": False, "error": str(e)}
-
- async def refresh_access_token(self, refresh_token: str) -> Dict[str, Any]:
- """
- Refresh an expired access token.
-
- Args:
- refresh_token: The refresh token from previous authorization
-
- Returns:
- Dict with new access_token, refresh_token, expires_in
- """
- data = {
- "grant_type": "refresh_token",
- "refresh_token": refresh_token,
- }
-
- headers = {"Content-Type": "application/x-www-form-urlencoded"}
-
- if self.client_secret:
- credentials = base64.b64encode(
- f"{self.client_id}:{self.client_secret}".encode()
- ).decode()
- headers["Authorization"] = f"Basic {credentials}"
- else:
- data["client_id"] = self.client_id
-
- try:
- async with httpx.AsyncClient(timeout=30.0) as client:
- response = await client.post(
- TOKEN_URL,
- data=data,
- headers=headers,
- )
-
- if response.status_code != 200:
- error_data = response.json() if response.text else {}
- logger.error(
- "Token refresh failed",
- status=response.status_code,
- error=error_data,
- )
- return {
- "success": False,
- "error": error_data.get("error_description", "Token refresh failed"),
- }
-
- token_data = response.json()
- logger.info("Twitter token refresh successful")
-
- return {
- "success": True,
- "access_token": token_data.get("access_token"),
- "refresh_token": token_data.get("refresh_token"),
- "expires_in": token_data.get("expires_in"),
- "scope": token_data.get("scope"),
- }
-
- except httpx.HTTPError as e:
- logger.error("HTTP error during token refresh", error=str(e))
- return {"success": False, "error": str(e)}
-
- async def revoke_token(self, token: str, token_type: str = "access_token") -> Dict[str, Any]:
- """
- Revoke an access or refresh token.
-
- Args:
- token: The token to revoke
- token_type: 'access_token' or 'refresh_token'
-
- Returns:
- Dict with success status
- """
- data = {
- "token": token,
- "token_type_hint": token_type,
- }
-
- headers = {"Content-Type": "application/x-www-form-urlencoded"}
-
- if self.client_secret:
- credentials = base64.b64encode(
- f"{self.client_id}:{self.client_secret}".encode()
- ).decode()
- headers["Authorization"] = f"Basic {credentials}"
- else:
- data["client_id"] = self.client_id
-
- try:
- async with httpx.AsyncClient(timeout=30.0) as client:
- response = await client.post(
- REVOKE_URL,
- data=data,
- headers=headers,
- )
-
- # 200 = success, even if token was already revoked
- if response.status_code == 200:
- logger.info("Twitter token revoked successfully")
- return {"success": True}
- else:
- error_data = response.json() if response.text else {}
- return {
- "success": False,
- "error": error_data.get("error_description", "Revocation failed"),
- }
-
- except httpx.HTTPError as e:
- logger.error("HTTP error during token revocation", error=str(e))
- return {"success": False, "error": str(e)}
-
+ scopes: Optional[List[str]] = None,
+ ) -> None:
+ super().__init__(
+ client_id=client_id,
+ redirect_uri=redirect_uri,
+ client_secret=client_secret,
+ scopes=scopes,
+ )
+
+ # Back-compat alias for the contract tests in
+ # tests/credentials/test_twitter_oauth.py -- the unified protocol
+ # method is :meth:`fetch_user_info`.
async def get_user_info(self, access_token: str) -> Dict[str, Any]:
- """
- Get authenticated user information.
-
- Args:
- access_token: Valid Twitter access token
+ return await self.fetch_user_info(access_token)
- Returns:
- Dict with user id, username, name, profile_image_url, verified
- """
+ async def fetch_user_info(self, access_token: str) -> Dict[str, Any]:
+ """Translate X's ``/users/me`` response into the unified shape."""
try:
async with httpx.AsyncClient(timeout=30.0) as client:
response = await client.get(
USER_INFO_URL,
- params={"user.fields": "id,name,username,profile_image_url,verified"},
+ params={
+ "user.fields": "id,name,username,profile_image_url,verified",
+ },
headers={"Authorization": f"Bearer {access_token}"},
)
+ except httpx.HTTPError as exc:
+ logger.error(f"[twitter] HTTP error getting user info: {exc}")
+ return {"success": False, "error": str(exc)}
+
+ if response.status_code != 200:
+ error_data = response.json() if response.text else {}
+ return {
+ "success": False,
+ "error": error_data.get("detail")
+ or error_data.get("title", "Failed to get user info"),
+ }
+
+ user = response.json().get("data", {})
+ return {
+ "success": True,
+ "id": user.get("id"),
+ "username": user.get("username"),
+ "name": user.get("name"),
+ "profile_image_url": user.get("profile_image_url"),
+ "verified": user.get("verified", False),
+ }
- if response.status_code != 200:
- error_data = response.json() if response.text else {}
- error_detail = error_data.get("detail") or error_data.get("title", "Failed to get user info")
- return {
- "success": False,
- "error": error_detail,
- }
-
- data = response.json()
- user = data.get("data", {})
-
- return {
- "success": True,
- "id": user.get("id"),
- "username": user.get("username"),
- "name": user.get("name"),
- "profile_image_url": user.get("profile_image_url"),
- "verified": user.get("verified", False),
- }
-
- except httpx.HTTPError as e:
- logger.error("HTTP error getting user info", error=str(e))
- return {"success": False, "error": str(e)}
-
-
-def cleanup_expired_states(max_age_seconds: int = 600):
- """
- Remove OAuth states older than max_age_seconds (default 10 minutes).
-
- Authorization codes expire in 30 seconds, so states older than a few
- minutes are definitely stale.
- """
- current_time = time.time()
- expired = [
- state
- for state, data in _oauth_states.items()
- if current_time - data["created_at"] > max_age_seconds
- ]
- for state in expired:
- _oauth_states.pop(state, None)
- if expired:
- logger.debug(f"Cleaned up {len(expired)} expired OAuth states")
+# Module-level alias for the contract tests' ``_oauth_states.clear()``
+# pattern -- this is the same dict the class-level state store wraps,
+# so clearing one clears the other.
+_oauth_states = TwitterOAuth.state_store._states
-def get_pending_state(state: str) -> Optional[Dict[str, Any]]:
- """Get pending OAuth state without removing it (for verification)."""
- return _oauth_states.get(state)
+__all__ = [
+ "TwitterOAuth",
+ "AUTHORIZATION_URL",
+ "TOKEN_URL",
+ "REVOKE_URL",
+ "USER_INFO_URL",
+]
diff --git a/server/nodes/twitter/_router.py b/server/nodes/twitter/_router.py
index 9569fafb..0cd0b85a 100644
--- a/server/nodes/twitter/_router.py
+++ b/server/nodes/twitter/_router.py
@@ -1,373 +1,29 @@
-"""
-Twitter/X OAuth 2.0 callback and API routes.
-
-OAuth flow:
-1. Frontend calls WebSocket 'twitter_oauth_login' handler
-2. Backend generates authorization URL, opens browser
-3. User authorizes on Twitter
-4. Twitter redirects to /api/twitter/callback with code
-5. Backend exchanges code for tokens, stores them via auth_service
-6. Frontend polls WebSocket 'twitter_oauth_status' for completion
+"""Twitter / X OAuth callback router — factory-built (Wave 11.I, S).
-Tokens stored as API keys with provider prefixes:
-- twitter_access_token: OAuth access token (expires in 2 hours)
-- twitter_refresh_token: OAuth refresh token (for token renewal)
+The single ``GET /api/twitter/callback`` route comes from
+:func:`services.events.oauth_lifecycle.make_oauth_callback_router`.
+Pre-S the file hand-rolled the callback + status + logout REST routes
+(~370 LOC). Status + logout were duplicates of the WS handlers in
+``_handlers.py`` and have been retired -- the WS path is canonical.
"""
-from typing import Optional
-
-from fastapi import APIRouter, Query, Request
-from fastapi.responses import HTMLResponse
-
-from core.logging import get_logger
-from nodes.twitter._oauth import TwitterOAuth, get_pending_state
-
-logger = get_logger(__name__)
-router = APIRouter(prefix="/api/twitter", tags=["twitter"])
-
-
-def get_auth_service():
- """Get auth service for API key storage. Imports lazily to avoid the
- nodes/<plugin>/__init__ -> core.container -> nodes.android._dispatcher
- -> nodes.android.__init__ -> _router import cycle."""
- from core.container import container
- return container.auth_service()
-
-
[email protected]("/callback")
-async def twitter_oauth_callback(
- code: Optional[str] = Query(None),
- state: Optional[str] = Query(None),
- error: Optional[str] = Query(None),
- error_description: Optional[str] = Query(None),
-):
- """
- Handle Twitter OAuth callback.
-
- Twitter redirects here after user authorizes (or denies) the app.
- We exchange the code for tokens and store them via auth_service.
- """
- # Handle authorization denied
- if error:
- logger.warning(f"Twitter OAuth denied: {error} - {error_description}")
- return HTMLResponse(
- content=_callback_html(
- success=False,
- error=error_description or error,
- ),
- status_code=200,
- )
-
- # Validate required parameters
- if not code or not state:
- logger.error("Twitter OAuth callback missing code or state")
- return HTMLResponse(
- content=_callback_html(
- success=False,
- error="Missing authorization code or state parameter",
- ),
- status_code=400,
- )
-
- # Verify state exists (CSRF protection)
- pending_state = get_pending_state(state)
- if not pending_state:
- logger.error("Twitter OAuth callback with invalid/expired state")
- return HTMLResponse(
- content=_callback_html(
- success=False,
- error="Invalid or expired authorization state. Please try again.",
- ),
- status_code=400,
- )
-
- # Retrieve redirect_uri from state (set during auth initiation)
- redirect_uri = pending_state.get("redirect_uri")
- if not redirect_uri:
- logger.error("Twitter OAuth callback missing redirect_uri in state")
- return HTMLResponse(
- content=_callback_html(
- success=False,
- error="Invalid state: missing redirect URI. Please try again.",
- ),
- status_code=400,
- )
-
- # Get stored client credentials to create OAuth instance
- auth_service = get_auth_service()
- client_id = await auth_service.get_api_key("twitter_client_id") or ""
- client_secret = await auth_service.get_api_key("twitter_client_secret")
-
- oauth = TwitterOAuth(
- client_id=client_id,
- client_secret=client_secret,
- redirect_uri=redirect_uri,
- )
-
- # Exchange code for tokens
- result = await oauth.exchange_code(code=code, state=state)
-
- if not result.get("success"):
- logger.error(f"Twitter token exchange failed: {result.get('error')}")
- return HTMLResponse(
- content=_callback_html(
- success=False,
- error=result.get("error", "Token exchange failed"),
- ),
- status_code=400,
- )
-
- # Get user info to display and store
- access_token = result.get("access_token")
- refresh_token = result.get("refresh_token")
- user_info = await oauth.get_user_info(access_token)
-
- if not user_info.get("success"):
- logger.warning(f"Failed to get Twitter user info: {user_info.get('error')}")
- username = "Unknown"
- else:
- username = user_info.get("username", "Unknown")
-
- # Store encrypted OAuth tokens via auth_service
- await auth_service.store_oauth_tokens(
- provider="twitter",
- access_token=access_token,
- refresh_token=refresh_token or "",
- email=f"@{username}", # Use @username as identifier (Twitter doesn't provide email)
- name=user_info.get("name", "") if user_info.get("success") else "",
- scopes=",".join(result.get("scope", "").split()) if result.get("scope") else "",
- customer_id="owner",
- )
-
- # Broadcast completion event to frontend
- from services.status_broadcaster import get_status_broadcaster
- broadcaster = get_status_broadcaster()
-
- await broadcaster.broadcast({
- "type": "twitter_oauth_complete",
- "data": {
- "success": True,
- "username": username,
- "user_id": user_info.get("id"),
- "name": user_info.get("name"),
- "profile_image_url": user_info.get("profile_image_url"),
- }
- })
-
- logger.info(f"Twitter OAuth successful for @{username}")
-
- return HTMLResponse(
- content=_callback_html(
- success=True,
- username=username,
- ),
- status_code=200,
- )
+from __future__ import annotations
+from typing import Any, Dict
-async def get_twitter_status(request: Request):
- """
- Get Twitter connection status.
+from services.events.oauth_lifecycle import make_oauth_callback_router
- Returns whether the user is authenticated with Twitter.
- """
- from services.oauth_utils import get_redirect_uri
+from ._handlers import _twitter_oauth_factory
- auth_service = get_auth_service()
- # Try to get stored tokens via auth_service
- tokens = await auth_service.get_oauth_tokens("twitter", customer_id="owner")
+def _user_info_to_email(info: Dict[str, Any]) -> str:
+ """X has no email field -- use ``@username`` as the identifier."""
+ return f"@{info.get('username', 'unknown')}"
- if not tokens:
- return {
- "connected": False,
- "username": None,
- "user_id": None,
- }
- access_token = tokens.get("access_token")
-
- # Get stored client credentials (these remain in auth_service as they're app-level)
- client_id = await auth_service.get_api_key("twitter_client_id") or ""
- client_secret = await auth_service.get_api_key("twitter_client_secret")
- redirect_uri = get_redirect_uri(request, "twitter")
-
- oauth = TwitterOAuth(
- client_id=client_id,
- client_secret=client_secret,
- redirect_uri=redirect_uri,
- )
-
- # Verify token is still valid by getting user info
- user_info = await oauth.get_user_info(access_token)
-
- if not user_info.get("success"):
- # Token may be expired, try to refresh — refresh_token is read
- # from the DB on demand (RFC 9700; not cached in memory).
- refresh_token = await auth_service.get_oauth_refresh_token(
- "twitter", customer_id="owner"
- )
- if refresh_token:
- refresh_result = await oauth.refresh_access_token(refresh_token)
- if refresh_result.get("success"):
- # Store new tokens via auth_service
- await auth_service.store_oauth_tokens(
- provider="twitter",
- access_token=refresh_result["access_token"],
- refresh_token=refresh_result.get("refresh_token") or refresh_token,
- email=tokens.get("email"),
- name=tokens.get("name"),
- scopes=tokens.get("scopes"),
- customer_id="owner",
- )
-
- # Retry user info
- user_info = await oauth.get_user_info(refresh_result["access_token"])
-
- if not user_info.get("success"):
- return {
- "connected": False,
- "username": None,
- "user_id": None,
- "error": user_info.get("error"),
- }
-
- return {
- "connected": True,
- "username": user_info.get("username"),
- "user_id": user_info.get("id"),
- "name": user_info.get("name"),
- "profile_image_url": user_info.get("profile_image_url"),
- "verified": user_info.get("verified"),
- }
-
-
-async def twitter_logout(request: Request):
- """
- Disconnect Twitter by revoking tokens and clearing stored credentials.
- """
- from services.oauth_utils import get_redirect_uri
-
- auth_service = get_auth_service()
-
- # Get stored tokens via auth_service
- tokens = await auth_service.get_oauth_tokens("twitter", customer_id="owner")
-
- if tokens:
- access_token = tokens.get("access_token")
- # refresh_token is not cached in memory (RFC 9700) — read from DB.
- refresh_token = await auth_service.get_oauth_refresh_token(
- "twitter", customer_id="owner"
- )
-
- # Get client credentials for revocation (app-level, in auth_service)
- client_id = await auth_service.get_api_key("twitter_client_id") or ""
- client_secret = await auth_service.get_api_key("twitter_client_secret")
- redirect_uri = get_redirect_uri(request, "twitter")
-
- oauth = TwitterOAuth(
- client_id=client_id,
- client_secret=client_secret,
- redirect_uri=redirect_uri,
- )
-
- # Revoke tokens
- if access_token:
- await oauth.revoke_token(access_token, "access_token")
-
- if refresh_token:
- await oauth.revoke_token(refresh_token, "refresh_token")
-
- # Clear stored credentials via auth_service
- await auth_service.remove_oauth_tokens("twitter", customer_id="owner")
-
- logger.info("Twitter disconnected and tokens revoked")
-
- return {"success": True, "message": "Twitter disconnected"}
-
-
-def _callback_html(success: bool, username: str = None, error: str = None) -> str:
- """Generate callback HTML page that closes itself and notifies parent."""
- if success:
- title = "Twitter Connected"
- message = f"Successfully connected as @{username}!"
- color = "#00ba7c" # Green
- else:
- title = "Connection Failed"
- message = error or "Failed to connect to Twitter"
- color = "#f4212e" # Red
-
- escaped_error = error.replace("'", "\\'") if error else ""
- return f"""
-<!DOCTYPE html>
-<html>
-<head>
- <title>{title}</title>
- <style>
- * {{ margin: 0; padding: 0; box-sizing: border-box; }}
- body {{
- font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
- background: linear-gradient(135deg, #15202b 0%, #1a1a2e 100%);
- min-height: 100vh;
- display: flex;
- align-items: center;
- justify-content: center;
- color: #fff;
- }}
- .container {{
- text-align: center;
- padding: 40px;
- background: rgba(255, 255, 255, 0.05);
- border-radius: 16px;
- border: 1px solid rgba(255, 255, 255, 0.1);
- max-width: 400px;
- }}
- .icon {{
- width: 64px;
- height: 64px;
- margin-bottom: 20px;
- color: {color};
- }}
- h1 {{
- font-size: 24px;
- margin-bottom: 12px;
- color: {color};
- }}
- p {{
- font-size: 16px;
- color: rgba(255, 255, 255, 0.8);
- margin-bottom: 20px;
- }}
- .close-text {{
- font-size: 14px;
- color: rgba(255, 255, 255, 0.5);
- }}
- </style>
-</head>
-<body>
- <div class="container">
- <svg class="icon" fill="none" stroke="currentColor" viewBox="0 0 24 24">
- {"<path stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z'/>" if success else "<path stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z'/>"}
- </svg>
- <h1>{title}</h1>
- <p>{message}</p>
- <p class="close-text">This window will close automatically...</p>
- </div>
- <script>
- // Notify parent window and close
- if (window.opener) {{
- window.opener.postMessage({{
- type: 'twitter_oauth_callback',
- success: {str(success).lower()},
- {"username: '" + username + "'," if username else ""}
- {"error: '" + escaped_error + "'," if error else ""}
- }}, '*');
- }}
- // Close after 2 seconds
- setTimeout(function() {{ window.close(); }}, 2000);
- </script>
-</body>
-</html>
-"""
+router = make_oauth_callback_router(
+ provider="twitter",
+ oauth_factory=_twitter_oauth_factory,
+ user_info_to_email=_user_info_to_email,
+ color_hex="#00ba7c", # X brand green for the success page
+)
diff --git a/server/services/events/oauth_lifecycle.py b/server/services/events/oauth_lifecycle.py
new file mode 100644
index 00000000..868a882d
--- /dev/null
+++ b/server/services/events/oauth_lifecycle.py
@@ -0,0 +1,523 @@
+"""OAuth lifecycle factory helpers (Wave 11.I, milestone S).
+
+Three factories that collapse the duplicated WS-handler / HTTP-router
+plumbing across :mod:`nodes.twitter` and :mod:`nodes.google`. Each
+plugin's ``_handlers.py`` and ``_router.py`` shrink to a single
+factory call.
+
+Companion to :mod:`services.events.lifecycle` (which factories the
+EventSource pattern Stripe uses). OAuth's lifecycle differs:
+
+* **EventSource** (Stripe): ``connect`` / ``disconnect`` / ``reconnect``
+ / ``status`` -- daemon-shaped.
+* **OAuth** (Twitter / Google): ``oauth_login`` / ``oauth_status`` /
+ ``logout`` -- browser-grant-shaped, plus an HTTP ``/callback`` route
+ the OAuth provider redirects the user back to.
+
+The factories are duck-typed against an ``oauth_factory()`` callable
+that returns either an :class:`OAuth2PKCEClient` subclass (Twitter,
+hand-rolled PKCE) or a composition wrapper around an upstream library
+(Google's ``google_auth_oauthlib.flow.Flow``). The methods consumed
+are:
+
+* ``generate_authorization_url(*, state_data=None) -> {url, state, ...}``
+* ``async exchange_code(code, state) -> {success, access_token,
+ refresh_token, expires_in, scope, ...}``
+* ``async fetch_user_info(access_token) -> {success, id, ...}``
+* ``async refresh_access_token(refresh_token) -> {success,
+ access_token, refresh_token, ...}``
+* ``async revoke_token(token, token_type) -> {success, ...}`` -- optional
+
+Persistence: in-memory state store. Same caveat as
+:mod:`services.plugin.oauth` -- popups opened across a server restart
+fail the callback CSRF check.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Dict, Optional, Protocol
+
+from fastapi import APIRouter, Query, Request, WebSocket
+from fastapi.responses import HTMLResponse
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+# ============================================================================
+# OAuthLike protocol -- duck-typed factory return value
+# ============================================================================
+
+
+class OAuthLike(Protocol):
+ """The minimal surface :func:`make_oauth_lifecycle_handlers` /
+ :func:`make_oauth_callback_router` need.
+
+ Both ``OAuth2PKCEClient`` (subclass mode) and Google's composition
+ wrapper conform.
+ """
+
+ def generate_authorization_url(
+ self, *, state_data: Optional[Dict[str, Any]] = None,
+ ) -> Dict[str, str]: ...
+
+ async def exchange_code(self, code: str, state: str) -> Dict[str, Any]: ...
+
+ async def fetch_user_info(self, access_token: str) -> Dict[str, Any]: ...
+
+ async def refresh_access_token(self, refresh_token: str) -> Dict[str, Any]: ...
+
+ async def revoke_token(
+ self, token: str, token_type: str = "access_token",
+ ) -> Dict[str, Any]: ...
+
+
+OAuthFactory = Callable[..., Awaitable[OAuthLike]]
+"""Async callable that builds an OAuth client. Accepts ``redirect_uri``
+keyword (passed by the lifecycle helpers). Implementations typically
+await ``auth_service.get_api_key`` for client_id / client_secret then
+construct the OAuth client. Plugins that don't need request context
+can ignore the kwarg."""
+
+
+# ============================================================================
+# make_oauth_lifecycle_handlers
+# ============================================================================
+
+
+def make_oauth_lifecycle_handlers(
+ *,
+ provider: str,
+ oauth_factory: OAuthFactory,
+ user_info_to_subject: Callable[[Dict[str, Any]], str],
+ legacy_status_broadcast: Optional[str] = None,
+ extra_logout: Optional[Callable[[], Awaitable[None]]] = None,
+) -> Dict[str, Callable]:
+ """Build the 3 WS handlers for an OAuth provider.
+
+ Returns ``{
+ f"{provider}_oauth_login": ...,
+ f"{provider}_oauth_status": ...,
+ f"{provider}_logout": ...,
+ }`` ready to feed :func:`services.ws_handler_registry.register_ws_handlers`.
+
+ Parameters:
+ provider:
+ Lowercase plugin id (``"twitter"``, ``"google"``). Used as
+ credential provider, broadcast subject, and message-type
+ prefix.
+ oauth_factory:
+ Builds an :class:`OAuthLike` instance per call. Receives
+ ``redirect_uri`` keyword. Implementations typically read
+ stored client_id / client_secret from ``auth_service`` and
+ compose the OAuth client.
+ user_info_to_subject:
+ Maps the unified user-info dict (returned by
+ ``fetch_user_info``) to the broadcast ``subject``: Twitter
+ uses ``f"@{username}"``, Google uses the email.
+ legacy_status_broadcast:
+ Optional wire-format type for a legacy status broadcast
+ that pre-dated the unified ``credential_catalogue_updated``
+ envelope. Google ships ``"google_status"`` for back-compat
+ with frontend code that grew up reading that frame.
+ extra_logout:
+ Optional async callback fired AFTER the standard logout
+ (revoke + remove tokens + broadcast). Twitter uses this to
+ drop legacy API-key entries from the pre-OAuth layout.
+ """
+
+ async def login(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ from core.container import container
+ from services.oauth_utils import get_redirect_uri
+
+ auth_service = container.auth_service()
+ client_id = await auth_service.get_api_key(f"{provider}_client_id")
+ if not client_id:
+ return {
+ "success": False,
+ "error": (
+ f"{provider.capitalize()} Client ID not configured. "
+ f"Add your {provider.capitalize()} API credentials first."
+ ),
+ }
+
+ redirect_uri = get_redirect_uri(websocket, provider)
+ oauth = await oauth_factory(redirect_uri=redirect_uri)
+ auth_data = oauth.generate_authorization_url()
+
+ return {
+ "success": True,
+ "message": f"Opening {provider.capitalize()} authorization in browser...",
+ "url": auth_data["url"],
+ "state": auth_data["state"],
+ }
+
+ async def status(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ from core.container import container
+ from services.oauth_utils import get_redirect_uri
+
+ auth_service = container.auth_service()
+ tokens = await auth_service.get_oauth_tokens(provider, customer_id="owner")
+ if not tokens or not tokens.get("access_token"):
+ # Match pre-S handler shape -- frontends key on these
+ # exact field names. Extra ``user_id``/``username``/...
+ # fields are absent on success too when the provider
+ # didn't return them, so callers must defensive-read.
+ payload = {"connected": False, "username": None, "user_id": None}
+ await _maybe_legacy_broadcast(legacy_status_broadcast, payload)
+ return payload
+
+ access_token = tokens["access_token"]
+ redirect_uri = get_redirect_uri(websocket, provider)
+ oauth = await oauth_factory(redirect_uri=redirect_uri)
+ user_info = await oauth.fetch_user_info(access_token)
+
+ # Silent refresh on token failure (RFC 9700: refresh_token not
+ # cached in memory; pull from DB on demand).
+ if not user_info.get("success"):
+ refresh_token = await auth_service.get_oauth_refresh_token(
+ provider, customer_id="owner",
+ )
+ if refresh_token:
+ refresh = await oauth.refresh_access_token(refresh_token)
+ if refresh.get("success"):
+ await auth_service.store_oauth_tokens(
+ provider=provider,
+ access_token=refresh["access_token"],
+ refresh_token=refresh.get("refresh_token") or refresh_token,
+ email=tokens.get("email", ""),
+ name=tokens.get("name", ""),
+ scopes=tokens.get("scopes", ""),
+ customer_id="owner",
+ )
+ user_info = await oauth.fetch_user_info(refresh["access_token"])
+
+ if not user_info.get("success"):
+ payload = {
+ "connected": False,
+ "username": None,
+ "user_id": None,
+ "error": user_info.get("error"),
+ }
+ await _maybe_legacy_broadcast(legacy_status_broadcast, payload)
+ return payload
+
+ payload = {
+ "connected": True,
+ **{k: v for k, v in user_info.items() if k != "success"},
+ }
+ await _maybe_legacy_broadcast(legacy_status_broadcast, payload)
+ return payload
+
+ async def logout(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ from core.container import container
+ from services.oauth_utils import get_redirect_uri
+ from services.status_broadcaster import get_status_broadcaster
+
+ auth_service = container.auth_service()
+ tokens = await auth_service.get_oauth_tokens(provider, customer_id="owner")
+ access_token = tokens.get("access_token") if tokens else None
+ refresh_token = (
+ await auth_service.get_oauth_refresh_token(provider, customer_id="owner")
+ if tokens else None
+ )
+
+ if access_token or refresh_token:
+ redirect_uri = get_redirect_uri(websocket, provider)
+ oauth = await oauth_factory(redirect_uri=redirect_uri)
+ if access_token:
+ await oauth.revoke_token(access_token, "access_token")
+ if refresh_token:
+ await oauth.revoke_token(refresh_token, "refresh_token")
+
+ await auth_service.remove_oauth_tokens(provider, customer_id="owner")
+
+ if extra_logout is not None:
+ try:
+ await extra_logout()
+ except Exception as exc: # noqa: BLE001 -- best-effort cleanup
+ logger.warning(f"[{provider}] extra_logout failed: {exc}")
+
+ broadcaster = get_status_broadcaster()
+ await broadcaster.broadcast_credential_event(
+ "credential.oauth.disconnected",
+ provider=provider,
+ customer_id="owner",
+ )
+
+ return {"success": True, "message": f"{provider.capitalize()} disconnected"}
+
+ return {
+ f"{provider}_oauth_login": login,
+ f"{provider}_oauth_status": status,
+ f"{provider}_logout": logout,
+ }
+
+
+async def _maybe_legacy_broadcast(
+ broadcast_type: Optional[str], payload: Dict[str, Any],
+) -> None:
+ """Optional legacy status broadcast (Google's ``google_status`` frame)."""
+ if not broadcast_type:
+ return
+ from services.status_broadcaster import get_status_broadcaster
+ await get_status_broadcaster().broadcast({"type": broadcast_type, "data": payload})
+
+
+# ============================================================================
+# make_oauth_callback_router
+# ============================================================================
+
+
+def make_oauth_callback_router(
+ *,
+ provider: str,
+ oauth_factory: OAuthFactory,
+ user_info_to_email: Callable[[Dict[str, Any]], str],
+ user_info_to_name: Callable[[Dict[str, Any]], str] = lambda info: info.get("name", "") or "",
+ extra_state_handler: Optional[Callable[[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]] = None,
+ color_hex: str = "#1DA1F2",
+) -> APIRouter:
+ """Build the FastAPI router with the OAuth callback endpoint.
+
+ Mounts ``GET /api/{provider}/callback`` -- the URI the OAuth
+ provider redirects to after the user authorises (or denies).
+
+ Parameters:
+ provider:
+ Lowercase plugin id; used as path prefix and broadcast type.
+ oauth_factory:
+ Builds an :class:`OAuthLike`. Same contract as for the
+ lifecycle handlers.
+ user_info_to_email:
+ Maps the unified user-info dict to the email/identifier
+ stored alongside the OAuth tokens. Twitter uses ``"@{username}"``;
+ Google uses ``info["email"]``.
+ user_info_to_name:
+ Display name extractor. Defaults to ``info.get("name", "")``.
+ extra_state_handler:
+ Optional async hook called with the decoded ``state_data``
+ from the state store BEFORE token storage. Returns an
+ override dict to mutate token storage args
+ (``customer_id``, ``redirect_after``, ...). Google uses
+ this to route customer-mode logins to the
+ ``google_connections`` table.
+ color_hex:
+ Brand colour for the success-page UI. Twitter ``#00ba7c``;
+ Google ``#4285F4``.
+ """
+
+ router = APIRouter(prefix=f"/api/{provider}", tags=[provider])
+
+ @router.get("/callback")
+ async def oauth_callback(
+ request: Request,
+ code: Optional[str] = Query(None),
+ state: Optional[str] = Query(None),
+ error: Optional[str] = Query(None),
+ error_description: Optional[str] = Query(None),
+ ):
+ if error:
+ logger.warning(f"{provider} OAuth denied: {error} - {error_description}")
+ return HTMLResponse(
+ content=render_oauth_callback_html(
+ provider, status="error",
+ message=error_description or error, color_hex=color_hex,
+ ),
+ status_code=200,
+ )
+
+ if not code or not state:
+ return HTMLResponse(
+ content=render_oauth_callback_html(
+ provider, status="error",
+ message="Missing authorization code or state parameter",
+ color_hex=color_hex,
+ ),
+ status_code=400,
+ )
+
+ oauth = await oauth_factory() # any redirect_uri override comes from state
+ # peek at state to read redirect_uri / state_data BEFORE the
+ # exchange (which pops it).
+ state_record = oauth.state_store.peek(state) if hasattr(oauth, "state_store") else None
+ redirect_uri = state_record.get("redirect_uri") if state_record else None
+ state_data = state_record.get("data") if state_record else {}
+
+ if redirect_uri:
+ # rebuild factory with the right redirect_uri so exchange_code
+ # POSTs the same URI the auth request used.
+ oauth = await oauth_factory(redirect_uri=redirect_uri)
+
+ result = await oauth.exchange_code(code, state)
+ if not result.get("success"):
+ return HTMLResponse(
+ content=render_oauth_callback_html(
+ provider, status="error",
+ message=result.get("error", "Token exchange failed"),
+ color_hex=color_hex,
+ ),
+ status_code=400,
+ )
+
+ access_token = result.get("access_token")
+ refresh_token = result.get("refresh_token") or ""
+
+ user_info = await oauth.fetch_user_info(access_token)
+ email = user_info_to_email(user_info) if user_info.get("success") else "Unknown"
+ name = user_info_to_name(user_info) if user_info.get("success") else ""
+
+ # Customer-mode hook (Google). Returns overrides for store_oauth_tokens
+ # plus an optional ``redirect_after`` URL.
+ store_overrides: Dict[str, Any] = {}
+ redirect_after: Optional[str] = None
+ if extra_state_handler is not None:
+ override = await extra_state_handler({
+ "state_data": state_data, "user_info": user_info,
+ "tokens": result,
+ })
+ if override:
+ redirect_after = override.pop("redirect_after", None)
+ store_overrides.update(override)
+
+ from core.container import container
+
+ auth_service = container.auth_service()
+ await auth_service.store_oauth_tokens(
+ provider=provider,
+ access_token=access_token,
+ refresh_token=refresh_token,
+ email=email,
+ name=name,
+ scopes=",".join((result.get("scope") or "").split()),
+ customer_id=store_overrides.pop("customer_id", "owner"),
+ **store_overrides,
+ )
+
+ # Broadcast completion (legacy provider-specific event for the
+ # popup-listening frontend) plus the symmetric catalogue-event.
+ from services.status_broadcaster import get_status_broadcaster
+
+ broadcaster = get_status_broadcaster()
+ await broadcaster.broadcast({
+ "type": f"{provider}_oauth_complete",
+ "data": {
+ "success": True,
+ **{k: v for k, v in user_info.items() if k != "success"},
+ },
+ })
+ await broadcaster.broadcast_credential_event(
+ "credential.oauth.connected",
+ provider=provider,
+ customer_id=store_overrides.get("customer_id", "owner"),
+ )
+
+ if redirect_after:
+ from fastapi.responses import RedirectResponse
+ return RedirectResponse(url=redirect_after, status_code=302)
+
+ return HTMLResponse(
+ content=render_oauth_callback_html(
+ provider, status="success",
+ message=f"Successfully connected as {email}!", color_hex=color_hex,
+ ),
+ status_code=200,
+ )
+
+ return router
+
+
+# ============================================================================
+# render_oauth_callback_html -- pure renderer
+# ============================================================================
+
+
+_HTML_TEMPLATE = """<!DOCTYPE html>
+<html>
+<head>
+ <title>{title}</title>
+ <style>
+ * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+ body {{
+ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+ background: linear-gradient(135deg, #15202b 0%, #1a1a2e 100%);
+ min-height: 100vh; display: flex; align-items: center;
+ justify-content: center; color: #fff;
+ }}
+ .container {{
+ text-align: center; padding: 40px;
+ background: rgba(255, 255, 255, 0.05);
+ border-radius: 16px; max-width: 400px;
+ border: 1px solid rgba(255, 255, 255, 0.1);
+ }}
+ .icon {{ width: 64px; height: 64px; margin-bottom: 20px; color: {color_hex}; }}
+ h1 {{ font-size: 24px; margin-bottom: 12px; color: {color_hex}; }}
+ p {{ font-size: 16px; color: rgba(255, 255, 255, 0.8); margin-bottom: 20px; }}
+ .close-text {{ font-size: 14px; color: rgba(255, 255, 255, 0.5); }}
+ </style>
+</head>
+<body>
+ <div class="container">
+ <svg class="icon" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+ {icon_path}
+ </svg>
+ <h1>{title}</h1>
+ <p>{message}</p>
+ <p class="close-text">This window will close automatically...</p>
+ </div>
+ <script>
+ if (window.opener) {{
+ window.opener.postMessage({{
+ type: '{provider}_oauth_callback',
+ success: {success_js},
+ message: '{message_js}',
+ }}, '*');
+ }}
+ setTimeout(function() {{ window.close(); }}, 2000);
+ </script>
+</body>
+</html>"""
+
+_SUCCESS_ICON = (
+ "<path stroke-linecap='round' stroke-linejoin='round' stroke-width='2' "
+ "d='M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z'/>"
+)
+_ERROR_ICON = (
+ "<path stroke-linecap='round' stroke-linejoin='round' stroke-width='2' "
+ "d='M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z'/>"
+)
+
+
+def render_oauth_callback_html(
+ provider: str, *, status: str, message: str, color_hex: str,
+) -> str:
+ """Render the small auto-closing callback page.
+
+ ``status`` MUST be ``"success"`` or ``"error"``. The page posts a
+ ``{provider}_oauth_callback`` message to ``window.opener`` (the
+ popup's parent) and auto-closes after 2 seconds.
+ """
+ is_success = status == "success"
+ title = (
+ f"{provider.capitalize()} Connected" if is_success
+ else "Connection Failed"
+ )
+ return _HTML_TEMPLATE.format(
+ title=title,
+ message=message,
+ color_hex=color_hex,
+ icon_path=_SUCCESS_ICON if is_success else _ERROR_ICON,
+ provider=provider,
+ success_js=str(is_success).lower(),
+ message_js=message.replace("'", "\\'"),
+ )
+
+
+__all__ = [
+ "OAuthLike",
+ "OAuthFactory",
+ "make_oauth_lifecycle_handlers",
+ "make_oauth_callback_router",
+ "render_oauth_callback_html",
+]
diff --git a/server/services/plugin/oauth.py b/server/services/plugin/oauth.py
new file mode 100644
index 00000000..81ecd843
--- /dev/null
+++ b/server/services/plugin/oauth.py
@@ -0,0 +1,381 @@
+"""OAuth 2.0 PKCE shared infrastructure (Wave 11.I, milestone S).
+
+Two pieces consumed by every OAuth-using plugin:
+
+1. :class:`OAuthStateStore` -- in-memory PKCE/state store with TTL.
+ Both Twitter (hand-rolled PKCE) and Google (``google_auth_oauthlib``-
+ wrapped) drive their callback CSRF check through one of these. The
+ pre-Wave-11.I plugin folders each hand-rolled their own ``dict`` +
+ ``cleanup_expired_states`` helper -- collapsed into this one class.
+
+2. :class:`OAuth2PKCEClient` -- abstract base for plugins that hand-roll
+ the OAuth 2.0 PKCE dance themselves (Twitter pattern). Subclass it
+ when the upstream API exposes a vanilla token endpoint and the
+ `Flow` class from `google_auth_oauthlib` doesn't fit. Override
+ :meth:`fetch_user_info` to translate the provider's profile API into
+ the unified ``{id, username, name, ...}`` shape consumed by the
+ lifecycle helpers in :mod:`services.events.oauth_lifecycle`.
+
+Plugins that compose around an upstream library (Google's
+``google_auth_oauthlib.flow.Flow``) skip the subclass and instantiate
+:class:`OAuthStateStore` directly. The lifecycle factory in
+:mod:`services.events.oauth_lifecycle` is duck-typed against the
+methods listed below -- both subclass and composition paths feed it
+without changes.
+
+Persistence: in-memory only. State resets on server restart -- a popup
+opened across a restart will fail the callback CSRF check. Same as
+pre-extraction behaviour. Persistent backing (Redis / DB) is a
+documented follow-up.
+
+Cleanup: lazy. The store exposes :meth:`OAuthStateStore.cleanup_expired`
+so plugins can prune from a periodic task; called on demand from the
+callback path so a flood of abandoned popups eventually self-clears
+without a background sweeper.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import time
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Dict, List, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+# ============================================================================
+# OAuthStateStore
+# ============================================================================
+
+
+class OAuthStateStore:
+ """In-memory PKCE/state store with TTL cleanup.
+
+ One instance per plugin (or one shared module-level instance).
+ Stores a payload (typically ``{code_verifier, redirect_uri,
+ state_data, created_at}``) keyed by the random ``state`` parameter
+ the OAuth flow round-trips through the browser.
+ """
+
+ DEFAULT_TTL_SECONDS = 600 # 10 minutes -- auth codes themselves expire faster
+
+ def __init__(self, *, ttl_seconds: int = DEFAULT_TTL_SECONDS) -> None:
+ self.ttl_seconds = ttl_seconds
+ self._states: Dict[str, Dict[str, Any]] = {}
+
+ def put(self, state: str, payload: Dict[str, Any]) -> None:
+ """Store a payload under ``state``. Stamps ``created_at``."""
+ record = dict(payload)
+ record.setdefault("created_at", time.time())
+ self._states[state] = record
+
+ def take(self, state: str) -> Optional[Dict[str, Any]]:
+ """Pop and return the payload for ``state``. One-shot.
+
+ This is the callback-path read: the state is consumed exactly
+ once when the user lands back on the redirect URI with the
+ ``code`` parameter.
+ """
+ return self._states.pop(state, None)
+
+ def peek(self, state: str) -> Optional[Dict[str, Any]]:
+ """Return the payload without removing it (read-only check).
+
+ Used by callback handlers that need to read the redirect_uri /
+ state_data BEFORE running the code exchange (which calls
+ :meth:`take`).
+ """
+ return self._states.get(state)
+
+ def cleanup_expired(self) -> int:
+ """Remove states older than ``ttl_seconds``. Returns count removed."""
+ now = time.time()
+ expired = [
+ state
+ for state, record in self._states.items()
+ if now - record.get("created_at", 0) > self.ttl_seconds
+ ]
+ for state in expired:
+ self._states.pop(state, None)
+ if expired:
+ logger.debug(f"OAuthStateStore: cleaned {len(expired)} expired states")
+ return len(expired)
+
+ def __len__(self) -> int:
+ return len(self._states)
+
+ def __contains__(self, state: object) -> bool:
+ return state in self._states
+
+
+# ============================================================================
+# PKCE helpers (RFC 7636)
+# ============================================================================
+
+
+def _generate_code_verifier() -> str:
+ """Cryptographically random PKCE code verifier (43-128 chars)."""
+ random_bytes = secrets.token_bytes(96)
+ verifier = base64.urlsafe_b64encode(random_bytes).rstrip(b"=").decode("ascii")
+ return verifier[:128]
+
+
+def _generate_code_challenge(code_verifier: str) -> str:
+ """S256 code challenge: ``BASE64URL(SHA256(code_verifier))``."""
+ digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+ return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def _generate_state() -> str:
+ """Random state parameter for CSRF protection (URL-safe)."""
+ return secrets.token_urlsafe(32)
+
+
+# ============================================================================
+# OAuth2PKCEClient (subclass-mode -- Twitter pattern)
+# ============================================================================
+
+
+class OAuth2PKCEClient(ABC):
+ """Hand-rolled OAuth 2.0 PKCE client.
+
+ Concrete subclasses override :attr:`provider`,
+ :attr:`authorization_endpoint`, :attr:`token_endpoint`,
+ optionally :attr:`revocation_endpoint`, and the
+ :meth:`fetch_user_info` translation. Everything else (PKCE state
+ management, code exchange, token refresh, optional revocation)
+ lives on this base.
+
+ Plugins that compose around a third-party Flow class (e.g.
+ Google's ``google_auth_oauthlib.flow.Flow``) skip this base and
+ instantiate :class:`OAuthStateStore` directly. The lifecycle
+ factory is duck-typed against these method signatures -- both
+ paths feed it identically.
+ """
+
+ provider: ClassVar[str] = ""
+ authorization_endpoint: ClassVar[str] = ""
+ token_endpoint: ClassVar[str] = ""
+ revocation_endpoint: ClassVar[str] = "" # optional
+
+ # Per-class shared state store. Plugins can override at class level
+ # if they want isolated TTLs / multiple instances.
+ state_store: ClassVar[OAuthStateStore] = OAuthStateStore()
+
+ DEFAULT_SCOPES: ClassVar[List[str]] = []
+
+ def __init__(
+ self,
+ client_id: str,
+ redirect_uri: str,
+ client_secret: Optional[str] = None,
+ scopes: Optional[List[str]] = None,
+ ) -> None:
+ if not self.provider:
+ raise ValueError(
+ f"{type(self).__name__} must set the ``provider`` ClassVar"
+ )
+ self.client_id = client_id
+ self.client_secret = client_secret
+ self.redirect_uri = redirect_uri
+ self.scopes = list(scopes) if scopes is not None else list(self.DEFAULT_SCOPES)
+
+ # ---- authorization-url generation ----------------------------------
+
+ def generate_authorization_url(
+ self,
+ *,
+ state_data: Optional[Dict[str, Any]] = None,
+ extra_params: Optional[Dict[str, str]] = None,
+ ) -> Dict[str, str]:
+ """Return the redirect URL + state + verifier.
+
+ Stashes ``code_verifier`` + ``redirect_uri`` (and any
+ caller-supplied ``state_data``) in :attr:`state_store` keyed by
+ the random state. The callback handler reads this back to
+ complete the exchange.
+ """
+ state = _generate_state()
+ code_verifier = _generate_code_verifier()
+ code_challenge = _generate_code_challenge(code_verifier)
+
+ self.state_store.put(state, {
+ "code_verifier": code_verifier,
+ "redirect_uri": self.redirect_uri,
+ "data": state_data or {},
+ })
+
+ params = {
+ "response_type": "code",
+ "client_id": self.client_id,
+ "redirect_uri": self.redirect_uri,
+ "scope": " ".join(self.scopes),
+ "state": state,
+ "code_challenge": code_challenge,
+ "code_challenge_method": "S256",
+ }
+ if extra_params:
+ params.update(extra_params)
+
+ return {
+ "url": f"{self.authorization_endpoint}?{urlencode(params)}",
+ "state": state,
+ "code_verifier": code_verifier,
+ }
+
+ # ---- token endpoint helpers ----------------------------------------
+
+ def _token_request_auth(self) -> tuple[Dict[str, str], Dict[str, str]]:
+ """Build (extra_body, extra_headers) for the token endpoint.
+
+ Confidential clients (with ``client_secret``) send Basic auth
+ in the header. Public clients put ``client_id`` in the body.
+ """
+ if self.client_secret:
+ credentials = base64.b64encode(
+ f"{self.client_id}:{self.client_secret}".encode()
+ ).decode()
+ return {}, {"Authorization": f"Basic {credentials}"}
+ return {"client_id": self.client_id}, {}
+
+ async def exchange_code(self, code: str, state: str) -> Dict[str, Any]:
+ """Exchange an auth code for tokens. Pops the state."""
+ record = self.state_store.take(state)
+ if not record:
+ logger.error(f"[{self.provider}] Invalid or expired OAuth state")
+ return {"success": False, "error": "Invalid or expired state"}
+
+ body = {
+ "grant_type": "authorization_code",
+ "code": code,
+ "redirect_uri": record.get("redirect_uri", self.redirect_uri),
+ "code_verifier": record["code_verifier"],
+ }
+ extra_body, extra_headers = self._token_request_auth()
+ body.update(extra_body)
+ headers = {"Content-Type": "application/x-www-form-urlencoded", **extra_headers}
+
+ try:
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ response = await client.post(
+ self.token_endpoint, data=body, headers=headers,
+ )
+ except httpx.HTTPError as exc:
+ logger.error(f"[{self.provider}] HTTP error during token exchange: {exc}")
+ return {"success": False, "error": str(exc)}
+
+ if response.status_code != 200:
+ error_data = response.json() if response.text else {}
+ logger.error(
+ f"[{self.provider}] Token exchange failed",
+ status=response.status_code, error=error_data,
+ )
+ return {
+ "success": False,
+ "error": error_data.get(
+ "error_description",
+ error_data.get("error", "Token exchange failed"),
+ ),
+ }
+
+ data = response.json()
+ return {
+ "success": True,
+ "access_token": data.get("access_token"),
+ "refresh_token": data.get("refresh_token"),
+ "expires_in": data.get("expires_in"),
+ "scope": data.get("scope"),
+ "token_type": data.get("token_type", "Bearer"),
+ }
+
+ async def refresh_access_token(self, refresh_token: str) -> Dict[str, Any]:
+ """Trade a refresh token for a fresh access token."""
+ body = {"grant_type": "refresh_token", "refresh_token": refresh_token}
+ extra_body, extra_headers = self._token_request_auth()
+ body.update(extra_body)
+ headers = {"Content-Type": "application/x-www-form-urlencoded", **extra_headers}
+
+ try:
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ response = await client.post(
+ self.token_endpoint, data=body, headers=headers,
+ )
+ except httpx.HTTPError as exc:
+ logger.error(f"[{self.provider}] HTTP error during token refresh: {exc}")
+ return {"success": False, "error": str(exc)}
+
+ if response.status_code != 200:
+ error_data = response.json() if response.text else {}
+ return {
+ "success": False,
+ "error": error_data.get("error_description", "Token refresh failed"),
+ }
+
+ data = response.json()
+ return {
+ "success": True,
+ "access_token": data.get("access_token"),
+ "refresh_token": data.get("refresh_token"),
+ "expires_in": data.get("expires_in"),
+ "scope": data.get("scope"),
+ }
+
+ async def revoke_token(
+ self, token: str, token_type: str = "access_token",
+ ) -> Dict[str, Any]:
+ """Revoke an access or refresh token (best-effort).
+
+ Subclasses without :attr:`revocation_endpoint` get a no-op
+ ``{"success": True, "skipped": True}`` so callers can always
+ attempt a revoke without branching.
+ """
+ if not self.revocation_endpoint:
+ return {"success": True, "skipped": True}
+
+ body = {"token": token, "token_type_hint": token_type}
+ extra_body, extra_headers = self._token_request_auth()
+ body.update(extra_body)
+ headers = {"Content-Type": "application/x-www-form-urlencoded", **extra_headers}
+
+ try:
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ response = await client.post(
+ self.revocation_endpoint, data=body, headers=headers,
+ )
+ except httpx.HTTPError as exc:
+ logger.error(f"[{self.provider}] HTTP error during token revoke: {exc}")
+ return {"success": False, "error": str(exc)}
+
+ if response.status_code == 200:
+ return {"success": True}
+ error_data = response.json() if response.text else {}
+ return {
+ "success": False,
+ "error": error_data.get("error_description", "Revocation failed"),
+ }
+
+ # ---- subclass override --------------------------------------------
+
+ @abstractmethod
+ async def fetch_user_info(self, access_token: str) -> Dict[str, Any]:
+ """Translate the provider's profile API into a unified shape.
+
+ MUST return ``{success: bool, ...}`` -- on success, include
+ ``id`` and at least one of ``username`` / ``email`` / ``name``.
+ The lifecycle factory uses these to populate the broadcast
+ envelope's ``subject`` and the connection-status payload.
+ """
+
+
+__all__ = [
+ "OAuthStateStore",
+ "OAuth2PKCEClient",
+]