### Summary Adds 3-legged "login + approve" Twitter/X auth (OAuth 2.0 Authorization Code + PKCE) to @elizaos/plugin-twitter without shipping any client secret, while keeping full backward compatibility with the existing env-var OAuth 1.0a credentials. Also adds a broker-ready auth mode stub (not functional yet) so a future Eliza-hosted broker can be added without touching tweet logic. This requires a “Twitter broker” I referenced below which is a future Eliza-hosted service (not implemented in this repo) that would sit between the plugin and Twitter to handle the parts that require a client secret and a user session. What it is A separate web service (owned by ElizaOS) that: - Runs the OAuth2 “login + approve” flow on behalf of users - Stores the client secret and refresh tokens securely - Hands the agent/plugin short‑lived access tokens (so the plugin never needs secrets) ### What changed in this PR (exact) - Introduced a single auth abstraction: TwitterAuthProvider#getAccessToken(): Promise - Added TWITTER_AUTH_MODE (env|oauth|broker) and centralized auth selection - env mode (default): preserves TWITTER_API_KEY / TWITTER_API_SECRET_KEY / TWITTER_ACCESS_TOKEN / TWITTER_ACCESS_TOKEN_SECRET behavior - oauth mode: OAuth2 PKCE interactive login + token refresh + persistence - broker mode: stub-only; fails clearly until an Eliza Twitter broker service exists - Refactored TwitterAuth + client call sites to use provider-driven tokens (no direct env reads in request logic) - Added unit tests for PKCE, OAuth2 refresh flows, token store, and broker stub - Updated docs and plugin parameter metadata ### Auth modes #### 1) Legacy env mode (no behavior change) Set: - TWITTER_AUTH_MODE=env (or omit) - TWITTER_API_KEY - TWITTER_API_SECRET_KEY - TWITTER_ACCESS_TOKEN - TWITTER_ACCESS_TOKEN_SECRET #### 2) OAuth2 PKCE mode ("login + approve") Set: - TWITTER_AUTH_MODE=oauth - TWITTER_CLIENT_ID - TWITTER_REDIRECT_URI (loopback recommended, e.g. http://127.0.0.1:8080/callback) Optional: - TWITTER_SCOPES (default: tweet.read tweet.write users.read offline.access) First run prints an authorization URL. After approval it stores tokens and auto-refreshes. Requires a ### Local callback server (required for best UX) In oauth mode, the plugin starts a small local HTTP server bound to 127.0.0.1 to capture the OAuth redirect at the host/port/path in TWITTER_REDIRECT_URI. - If it can’t bind, it falls back to "paste the redirected URL". ### Broker mode (stub; requires Eliza Twitter broker server) If TWITTER_AUTH_MODE=broker: - Requires TWITTER_BROKER_URL - This PR does NOT implement the broker server; it only provides the plugin-side provider stub. - Later, an Eliza-hosted broker (e.g. eliza twitter auth server) can hold the client secret and return short-lived access tokens. ### Validation - bun run build - bun run test:coverage (unit tests; E2E stays env-mode only / skipped without credentials)

Greptile Summary

- Introduces OAuth2 PKCE authentication mode for Twitter/X integration while preserving backward compatibility with existing OAuth 1.0a environment variable credentials - Implements auth provider abstraction with three modes: 'env' (default legacy), 'oauth' (OAuth2 PKCE), and 'broker' (stub for future hosted service) - Adds interactive "login + approve" flow with local callback server, automatic token refresh, token persistence, and comprehensive error handling

Important Files Changed

| Filename | Overview | |----------|----------| | `src/client/auth-providers/oauth2-pkce.ts` | New OAuth2 PKCE authentication provider with interactive login, token refresh, and persistence | | `src/client/auth.ts` | Refactored to use provider abstraction; made `getV2Client()` async, added lazy initialization and token refresh detection | | `src/environment.ts` | Added `TWITTER_AUTH_MODE` configuration with mode-specific validation for env/oauth/broker authentication | | `src/client/tweets.ts` | Updated all API client retrieval calls to be async to support dynamic token operations | | `src/index.ts` | Modified plugin initialization to validate credentials based on selected auth mode instead of hardcoded OAuth 1.0a |

Confidence score: 4/5

- This PR introduces significant but well-architected changes that maintain backward compatibility - Score reflects comprehensive testing coverage, clean abstractions, and thorough error handling, but deducted one point due to the complexity of authentication refactoring affecting many files - Pay close attention to the async changes in `tweets.ts`, `relationships.ts`, `profile.ts`, and `search.ts` to ensure all callers handle Promise rejections properly

Sequence Diagram

```mermaid sequenceDiagram participant User participant Plugin as TwitterPlugin participant Provider as OAuth2PKCEAuthProvider participant TwitterAPI as Twitter/X API participant TokenStore as Token Store participant Browser User->>Plugin: "Initialize with TWITTER_AUTH_MODE=oauth" Plugin->>Provider: "createTwitterAuthProvider(runtime, state)" Provider->>TokenStore: "load()" TokenStore-->>Provider: "null (no existing tokens)" User->>Plugin: "Perform Twitter action (post tweet, etc.)" Plugin->>Provider: "getAccessToken()" Provider->>Provider: "interactiveLogin()" Provider->>Provider: "createCodeVerifier() & createCodeChallenge()" Provider->>Provider: "buildAuthorizeUrl(state, codeChallenge)" Provider->>User: "Print authorization URL" User->>Browser: "Open authorization URL" Browser->>TwitterAPI: "GET /oauth2/authorize with PKCE params" TwitterAPI-->>Browser: "User consent page" User->>Browser: "Approve application" Browser->>Provider: "Redirect with authorization code" Provider->>TwitterAPI: "POST /oauth2/token with code & verifier" TwitterAPI-->>Provider: "access_token + refresh_token + expires_in" Provider->>TokenStore: "save(tokens)" Provider-->>Plugin: "access_token" Plugin->>TwitterAPI: "API call with Bearer token" TwitterAPI-->>Plugin: "API response" Plugin-->>User: "Success" ``` ## Summary by CodeRabbit * **New Features** * Added interactive OAuth2 PKCE login and a broker option alongside legacy env-based auth * New authenticate() entrypoint and mode-aware client initialization for Twitter integration * **Documentation** * Reworked auth setup docs to explain auth-mode choices, PKCE flow, and mode-specific troubleshooting * Updated test guides to reflect auth-mode behaviors * **Configuration** * New TWITTER_AUTH_MODE plus client ID, redirect URI, scopes, and broker URL settings * **Tests** * Added suites for PKCE, token stores, OAuth provider behaviors, and broker validation * **Chores** * Ignore local OAuth token files and related artifacts in repo ignore list _{✏️ Tip: You can customize this high-level summary in your review settings.}

elizaOS

🏗️ Work in Progress

New Pull Requests