machinaos 0.0.21 → 0.0.23

package/server/services/twitter_oauth.py

@@ -0,0 +1,410 @@
+"""
+Twitter/X OAuth 2.0 with PKCE - Browser-based login flow for X API v2.
+
+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
+
+Access tokens expire in 2 hours by default. Use offline.access scope for refresh tokens.
+Authorization codes expire in 30 seconds.
+"""
+
+import base64
+import hashlib
+import secrets
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+# X API OAuth 2.0 endpoints (updated URLs per latest docs)
+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
+# 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)
+]
+
+# 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")
+
+        # Step 1: Generate authorization URL
+        auth_data = oauth.generate_authorization_url()
+        # Redirect user to auth_data["url"]
+
+        # Step 2: Handle callback and exchange code
+        tokens = await oauth.exchange_code(code="...", state="...")
+
+        # Step 3: Use access_token for API calls
+        user_info = await oauth.get_user_info(tokens["access_token"])
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: Optional[str] = None,
+        redirect_uri: str = "http://localhost:3010/api/twitter/callback",
+        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(),
+        }
+
+        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)}
+
+    async def get_user_info(self, access_token: str) -> Dict[str, Any]:
+        """
+        Get authenticated user information.
+
+        Args:
+            access_token: Valid Twitter access token
+
+        Returns:
+            Dict with user id, username, name, profile_image_url, verified
+        """
+        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"},
+                    headers={"Authorization": f"Bearer {access_token}"},
+                )
+
+                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")
+
+
+def get_pending_state(state: str) -> Optional[Dict[str, Any]]:
+    """Get pending OAuth state without removing it (for verification)."""
+    return _oauth_states.get(state)

package/server/skills/social_agent/twitter-search-skill/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: twitter-search-skill
+description: Search for recent tweets on Twitter/X using keywords, hashtags, mentions, and advanced query operators.
+allowed-tools: twitter_search
+metadata:
+  author: machina
+  version: "1.0"
+  category: social
+  icon: "🔍"
+  color: "#000000"
+---
+
+# Twitter Search Tool
+
+Search for recent tweets on Twitter/X.
+
+## How It Works
+
+This skill provides instructions for the **Twitter Search** tool node. Connect the **Twitter Search** node to an AI Agent's `input-tools` handle to enable tweet searching.
+
+## twitter_search Tool
+
+Search for tweets matching a query.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| query | string | Yes | Search query (supports operators) |
+| max_results | integer | No | Number of results (10-100, default: 10) |
+
+### Query Operators
+
+The X API supports advanced search operators:
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| keyword | `python` | Tweets containing the word |
+| phrase | `"machine learning"` | Exact phrase match |
+| hashtag | `#AI` | Tweets with hashtag |
+| mention | `@username` | Tweets mentioning user |
+| from | `from:elonmusk` | Tweets by specific user |
+| to | `to:username` | Replies to user |
+| -keyword | `-spam` | Exclude keyword |
+| OR | `python OR javascript` | Either term |
+| lang | `lang:en` | Language filter |
+| has:links | `AI has:links` | Tweets with URLs |
+| has:media | `sunset has:media` | Tweets with media |
+| is:retweet | `bitcoin is:retweet` | Only retweets |
+| -is:retweet | `news -is:retweet` | Exclude retweets |
+
+### Examples
+
+**Simple keyword search:**
+```json
+{
+  "query": "artificial intelligence",
+  "max_results": 20
+}
+```
+
+**Search with hashtag:**
+```json
+{
+  "query": "#MachineLearning",
+  "max_results": 50
+}
+```
+
+**Search tweets from a user:**
+```json
+{
+  "query": "from:OpenAI",
+  "max_results": 10
+}
+```
+
+**Complex query:**
+```json
+{
+  "query": "AI (startup OR company) -is:retweet lang:en",
+  "max_results": 100
+}
+```
+
+**Search with media:**
+```json
+{
+  "query": "sunset has:media",
+  "max_results": 25
+}
+```
+
+### Response Format
+
+```json
+{
+  "success": true,
+  "result": {
+    "tweets": [
+      {
+        "id": "1234567890123456789",
+        "text": "Exciting developments in AI...",
+        "author_id": "987654321",
+        "created_at": "2025-02-19T10:30:00Z"
+      }
+    ],
+    "count": 20,
+    "query": "#AI"
+  },
+  "execution_time": 0.82
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": "Search query is required",
+  "execution_time": 0.01
+}
+```
+
+## Guidelines
+
+1. **Query length**: Keep queries concise for better results
+2. **Max results**: Limited to 100 per request (API constraint)
+3. **Recent tweets only**: X API v2 free tier searches recent tweets (last 7 days)
+4. **Rate limits**: Be mindful of API rate limits when searching repeatedly
+5. **Combine operators**: Use multiple operators for precise filtering
+
+## Common Use Cases
+
+- Monitor brand mentions
+- Track trending topics
+- Find tweets about specific subjects
+- Research competitor activity
+- Gather content for curation
+- Find influencers discussing topics
+
+## Setup Requirements
+
+1. Connect the **Twitter Search** node to an AI Agent's `input-tools` handle
+2. Ensure Twitter is connected (authenticated via OAuth in Credentials Modal)
+3. Your X Developer account must have appropriate API access level

package/server/skills/social_agent/twitter-send-skill/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: twitter-send-skill
+description: Post tweets, reply to tweets, retweet, like/unlike, and delete tweets on Twitter/X.
+allowed-tools: twitter_send
+metadata:
+  author: machina
+  version: "1.0"
+  category: social
+  icon: "📤"
+  color: "#000000"
+---
+
+# Twitter Send Tool
+
+Post and interact with tweets on Twitter/X.
+
+## How It Works
+
+This skill provides instructions for the **Twitter Send** tool node. Connect the **Twitter Send** node to an AI Agent's `input-tools` handle to enable posting and interactions.
+
+## twitter_send Tool
+
+Send tweets, replies, retweets, likes, and deletions.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| action | string | Yes | Action type: `tweet`, `reply`, `retweet`, `like`, `unlike`, `delete` |
+| text | string | If tweet/reply | Tweet text content (max 280 characters) |
+| tweet_id | string | If retweet/like/unlike/delete | Target tweet ID |
+| reply_to_id | string | If reply | Tweet ID to reply to |
+
+### Actions
+
+| Action | Required Fields | Description |
+|--------|-----------------|-------------|
+| `tweet` | text | Post a new tweet |
+| `reply` | text, reply_to_id | Reply to an existing tweet |
+| `retweet` | tweet_id | Retweet an existing tweet |
+| `like` | tweet_id | Like a tweet |
+| `unlike` | tweet_id | Remove like from a tweet |
+| `delete` | tweet_id | Delete your own tweet |
+
+### Examples
+
+**Post a tweet:**
+```json
+{
+  "action": "tweet",
+  "text": "Hello Twitter! This is my first automated tweet."
+}
+```
+
+**Reply to a tweet:**
+```json
+{
+  "action": "reply",
+  "text": "Thanks for sharing this!",
+  "reply_to_id": "1234567890123456789"
+}
+```
+
+**Retweet:**
+```json
+{
+  "action": "retweet",
+  "tweet_id": "1234567890123456789"
+}
+```
+
+**Like a tweet:**
+```json
+{
+  "action": "like",
+  "tweet_id": "1234567890123456789"
+}
+```
+
+**Unlike a tweet:**
+```json
+{
+  "action": "unlike",
+  "tweet_id": "1234567890123456789"
+}
+```
+
+**Delete a tweet:**
+```json
+{
+  "action": "delete",
+  "tweet_id": "1234567890123456789"
+}
+```
+
+### Response Format
+
+```json
+{
+  "success": true,
+  "result": {
+    "data": {
+      "id": "1234567890123456789",
+      "text": "Hello Twitter!"
+    },
+    "action": "tweet_sent"
+  },
+  "execution_time": 0.45
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": "Tweet text is required",
+  "execution_time": 0.01
+}
+```
+
+## Guidelines
+
+1. **Character limit**: Tweets are limited to 280 characters
+2. **Tweet IDs**: Use the numeric ID string (e.g., `1234567890123456789`)
+3. **Rate limits**: X API has rate limits - avoid rapid posting
+4. **Content policy**: Follow X's content policies and terms of service
+5. **Threading**: Use reply action with reply_to_id to create threads
+
+## Common Use Cases
+
+- Post automated updates and announcements
+- Reply to mentions or specific tweets
+- Like tweets matching certain criteria
+- Create tweet threads by chaining replies
+- Engage with followers programmatically
+
+## Setup Requirements
+
+1. Connect the **Twitter Send** node to an AI Agent's `input-tools` handle
+2. Ensure Twitter is connected (authenticated via OAuth in Credentials Modal)
+3. Your X Developer account must have appropriate API access level