trading-platform/docs/02-definicion-modulos/OQI-001-fundamentos-auth/historias-usuario/US-AUTH-005-oauth-twitter.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-AUTH-005	OAuth Twitter/X	User Story	To Do	Alta	OQI-001	3	2025-12-05	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

---

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:

  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

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

Especificaciones Relacionadas

• ET-AUTH-002: JWT Tokens
• ET-AUTH-004: OAuth Integration