---
id: "US-AUTH-005"
title: "OAuth Twitter/X"
type: "User Story"
status: "To Do"
priority: "Alta"
epic: "OQI-001"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-AUTH-005: OAuth Twitter/X

**Version:** 1.0.0
**Fecha:** 2025-12-05
**Estado:** Pendiente
**Story Points:** 3
**Prioridad:** P1 (Alta)
**Épica:** [OQI-001](../_MAP.md)

---

## Historia de Usuario

**Como** visitante o usuario de Trading Platform
**Quiero** poder registrarme e iniciar sesión usando mi cuenta de Twitter/X
**Para** tener un acceso rápido sin crear una nueva contraseña

---

## Criterios de Aceptación

### AC-001: Botón de Twitter/X visible

**Dado** que estoy en la página de registro o login
**Cuando** veo las opciones de autenticación
**Entonces** debería ver un botón "Continuar con X"
**Y** debería tener el logo y estilo oficial de X (antes Twitter)

### AC-002: Flujo de OAuth

**Dado** que hago click en "Continuar con X"
**Cuando** se abre la ventana de autorización
**Entonces** debería:
1. Ver la pantalla de autorización de X
2. Poder revisar los permisos solicitados
3. Poder autorizar la aplicación

### AC-003: Permisos solicitados

**Dado** que estoy en la pantalla de autorización de X
**Cuando** reviso los permisos
**Entonces** la app debería solicitar:
- Leer información de perfil
- Email (si está disponible)

### AC-004: Primer registro exitoso

**Dado** que es mi primera vez usando X OAuth
**Cuando** autorizo los permisos
**Entonces** debería:
1. Crear mi cuenta automáticamente
2. Recibir un JWT token
3. Ser redirigido al dashboard
4. Ver mi nombre y foto de X
5. Si X no proporciona email, solicitar email adicional

### AC-005: Solicitud de email adicional

**Dado** que X no proporcionó mi email
**Cuando** completo la autorización
**Entonces** debería ver un formulario que solicita:
- "Completa tu registro: ingresa tu email"
**Y** debería validar que el email no esté en uso
**Y** debería enviar email de verificación

### AC-006: Login existente

**Dado** que ya tengo una cuenta vinculada con X
**Cuando** uso "Continuar con X"
**Entonces** debería:
1. Iniciar sesión automáticamente
2. Ser redirigido al dashboard

### AC-007: Email ya registrado

**Dado** que mi email de X ya está registrado con otro método
**Cuando** intento usar X OAuth
**Entonces** debería ver opción de vincular cuentas
**Y** debería poder vincular después de autenticarme

### AC-008: Cancelación del flujo

**Dado** que inicio el flujo de X OAuth
**Cuando** cancelo en la ventana de X
**Entonces** debería volver a login/registro
**Y** ver mensaje "Autenticación cancelada"

---

## Mockup

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│              🌟 Bienvenido a Trading Platform                     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               📧 Email                               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          🔴 Continuar con Google                     │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          ⚫ Continuar con X                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [Facebook]  [Apple]  [GitHub]                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Ventana de X OAuth:
┌─────────────────────────────────────────────────────────────┐
│  x.com                                                 ✕    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│              Autorizar Trading Platform                            │
│                                                             │
│  Esta aplicación podrá:                                     │
│                                                             │
│  • Ver tu perfil y posts                                    │
│  • Ver los perfiles que sigues                              │
│  • Actualizar tu perfil                                     │
│                                                             │
│  @juanperez                                                 │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Autorizar aplicación                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Cancelar                                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Formulario adicional si falta email:
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│          Un último paso para completar tu registro          │
│                                                             │
│  X no compartió tu email. Por favor ingrésalo:             │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Email                                                │   │
│  │ ┌─────────────────────────────────────────────────┐ │   │
│  │ │ tu@email.com                                     │ │   │
│  │ └─────────────────────────────────────────────────┘ │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Completar registro                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Tareas Técnicas

### Database (DB)

- [ ] Agregar campos a tabla `users`:
  ```sql
  ALTER TABLE users ADD COLUMN twitter_id VARCHAR(255) UNIQUE;
  ALTER TABLE users ADD COLUMN twitter_username VARCHAR(255);
  ```
- [ ] Usar tabla `oauth_connections` existente
- [ ] Índice en `twitter_id`

### Backend (BE)

- [ ] Configurar X Developer App
- [ ] Obtener API Key y API Secret
- [ ] Endpoint `GET /api/v1/auth/twitter`
  - Redirige a X OAuth
- [ ] Endpoint `GET /api/v1/auth/twitter/callback`
  - Recibe código de autorización
  - Intercambia por access token
  - Obtiene datos del usuario
  - Verifica si email está disponible
  - Crea o actualiza usuario
  - Genera JWT token
- [ ] Endpoint `POST /api/v1/auth/twitter/complete-email`
  - Para usuarios sin email de X
  - Valida email
  - Envía verificación
- [ ] Service `TwitterOAuthService`
  - `getAuthorizationUrl()`
  - `exchangeCodeForToken()`
  - `getUserProfile()`
  - `linkAccount()`
- [ ] Tests unitarios (10 casos)
- [ ] Tests de integración con mock de X API

### Frontend (FE)

- [ ] Botón "Continuar con X"
- [ ] Manejo de popup/redirect OAuth
- [ ] Componente `CompleteEmailForm.tsx`
- [ ] Recepción de callback
- [ ] Almacenamiento de token JWT
- [ ] Estado de loading
- [ ] Manejo de errores
- [ ] Tests con React Testing Library

### Testing (QA)

- [ ] E2E: Registro con X (con email)
- [ ] E2E: Registro con X (sin email, completar manualmente)
- [ ] E2E: Login existente con X
- [ ] E2E: Vinculación de cuentas
- [ ] E2E: Cancelación del flujo
- [ ] Test de seguridad: Validación de tokens
- [ ] Test de seguridad: CSRF protection
- [ ] Mock de X API para tests

---

## Dependencias

- **Bloqueantes:**
  - Cuenta de X Developer (con nivel Elevated o superior)
  - Configuración de OAuth 2.0 en X Developer Portal
  - SSL/HTTPS en producción

- **Deseables:**
  - US-AUTH-003: Consistencia con otros OAuth
  - US-AUTH-004: Patrón similar a Facebook OAuth

---

## Definition of Ready (DoR)

- [ ] X Developer App creada
- [ ] Credenciales OAuth 2.0 disponibles
- [ ] Mockups aprobados
- [ ] API contract definido
- [ ] Flujo de email adicional diseñado

---

## Definition of Done (DoD)

- [ ] Código implementado y revisado
- [ ] Tests unitarios con 80%+ cobertura
- [ ] Tests de integración pasando
- [ ] Tests E2E implementados
- [ ] Documentación actualizada
- [ ] Manejo de errores completo
- [ ] Flujo de email adicional funcional
- [ ] Logs implementados
- [ ] QA aprobado en staging
- [ ] Deploy a producción exitoso

---

## Notas Técnicas

### Twitter/X OAuth 2.0 Flow

1. Frontend redirige a `/api/v1/auth/twitter`
2. Backend redirige a X con:
   - `client_id`
   - `redirect_uri`
   - `scope=tweet.read users.read offline.access`
   - `state` (CSRF token)
   - `code_challenge` (PKCE)
3. Usuario autoriza en X
4. X redirige a `redirect_uri` con `code`
5. Backend intercambia `code` por `access_token`
6. Backend obtiene perfil del usuario
7. Si no hay email, redirige a formulario adicional
8. Backend crea/actualiza usuario
9. Backend genera JWT

### X API v2 Endpoints

- Authorization: `https://twitter.com/i/oauth2/authorize`
- Token exchange: `https://api.twitter.com/2/oauth2/token`
- User info: `https://api.twitter.com/2/users/me?user.fields=profile_image_url`

### Environment Variables

```env
TWITTER_CLIENT_ID=your_client_id
TWITTER_CLIENT_SECRET=your_client_secret
TWITTER_CALLBACK_URL=https://trading.com/api/v1/auth/twitter/callback
```

### Consideraciones Especiales de X

- X no siempre proporciona email del usuario
- Requiere OAuth 2.0 con PKCE
- Necesita scope `offline.access` para refresh tokens
- Rate limits más estrictos que otros proveedores
- Requiere X Developer Account con nivel "Elevated" mínimo

### Security Considerations

- Implementar PKCE (Proof Key for Code Exchange)
- Validar `state` parameter (CSRF)
- Validar email adicional si es requerido
- Rate limiting en endpoints
- Logs de intentos de autenticación

---

## Requerimientos Relacionados

- [RF-AUTH-003: OAuth Social](../requerimientos/RF-AUTH-003-oauth.md)

## Especificaciones Relacionadas

- [ET-AUTH-002: JWT Tokens](../especificaciones/ET-AUTH-002-jwt.md)
- [ET-AUTH-004: OAuth Integration](../especificaciones/ET-AUTH-004-oauth.md)