Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
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.pyindex 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_handlersfrom ._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 containerauth_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 containerauth_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.pyindex 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, Optionalimport httpxfrom core.logging import get_logger+from services.plugin.oauth import OAuth2PKCEClient, OAuthStateStorelogger = 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_SCOPESdef __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.pyindex 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[email protected]("/status")-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"),- }--[email protected]("/logout")-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.pynew file mode 100644index 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.pynew file mode 100644index 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",+]