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

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-AUTH-007	OAuth GitHub	User Story	To Do	Media	OQI-001	3	2025-12-05	2026-01-04

US-AUTH-007: OAuth GitHub

Version: 1.0.0 Fecha: 2025-12-05 Estado: Pendiente Story Points: 3 Prioridad: P2 (Media) Épica: OQI-001

---

Historia de Usuario

Como desarrollador o usuario técnico de Trading Platform Quiero poder registrarme e iniciar sesión usando mi cuenta de GitHub Para tener un acceso rápido usando mis credenciales de desarrollador

---

Criterios de Aceptación

AC-001: Botón de GitHub 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 GitHub" Y debería tener el logo oficial de GitHub

AC-002: Flujo de OAuth

Dado que hago click en "Continuar con GitHub" Cuando se abre la ventana de GitHub Entonces debería:

1. Ver la pantalla de autorización de GitHub
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 GitHub Cuando reviso los permisos Entonces la app debería solicitar únicamente:

• user:email (para leer email)
• read:user (para leer perfil básico)

AC-004: Primer registro exitoso

Dado que es mi primera vez usando GitHub 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 avatar de GitHub
5. Usar mi email primario de GitHub

AC-005: Email primario privado

Dado que tengo mi email configurado como privado en GitHub Cuando autorizo la aplicación Entonces debería usar mi email noreply de GitHub O solicitar un email alternativo

AC-006: Login existente

Dado que ya tengo una cuenta vinculada con GitHub Cuando uso "Continuar con GitHub" Entonces debería:

1. Iniciar sesión automáticamente
2. Ser redirigido al dashboard

AC-007: Múltiples emails en GitHub

Dado que tengo múltiples emails en mi cuenta de GitHub Cuando autorizo la aplicación Entonces debería usar el email marcado como primario Y debería verificar que no esté ya registrado

AC-008: Cancelación del flujo

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

---

Mockup

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

Ventana de GitHub OAuth:
┌─────────────────────────────────────────────────────────────┐
│  github.com                                            ✕    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│              Authorize Trading Platform                            │
│                                                             │
│  Trading Platform by Trading Platform Team                                │
│  wants to access your juanperez account                     │
│                                                             │
│  This application will be able to:                          │
│                                                             │
│  ✓ Verify your GitHub identity                             │
│  ✓ Read your email addresses                               │
│  ✓ Read your profile information                           │
│                                                             │
│  Authorizing will redirect to:                              │
│  https://trading.com/api/v1/auth/github/callback          │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         Authorize Trading Platform                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Cancel                                                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Tareas Técnicas

Database (DB)

• Agregar campos a tabla users:

  ALTER TABLE users ADD COLUMN github_id VARCHAR(255) UNIQUE;
  ALTER TABLE users ADD COLUMN github_username VARCHAR(255);
  

• Usar tabla oauth_connections existente
• Índice en github_id

Backend (BE)

• Crear GitHub OAuth App
• Obtener Client ID y Client Secret
• Endpoint GET /api/v1/auth/github
  • Redirige a GitHub OAuth
• Endpoint GET /api/v1/auth/github/callback
  • Recibe código de autorización
  • Intercambia por access token
  • Obtiene perfil del usuario
  • Obtiene emails del usuario
  • Selecciona email primario
  • Crea o actualiza usuario
  • Genera JWT token
• Service GitHubOAuthService
  • getAuthorizationUrl()
  • exchangeCodeForToken()
  • getUserProfile()
  • getUserEmails()
  • selectPrimaryEmail()
  • linkAccount()
• Tests unitarios (8 casos)
• Tests de integración con mock de GitHub API

Frontend (FE)

• Botón "Continuar con GitHub"
• Manejo de popup/redirect OAuth
• Recepción de callback
• Almacenamiento de token JWT
• Estado de loading
• Manejo de errores
• Tests con React Testing Library

Testing (QA)

• E2E: Registro con GitHub
• E2E: Login existente
• E2E: Email privado/noreply
• E2E: Múltiples emails
• E2E: Cancelación del flujo
• Test de seguridad: Validación de tokens
• Test de seguridad: CSRF protection
• Mock de GitHub API

---

Dependencias

• Bloqueantes:

  • GitHub OAuth App creada
  • Credenciales configuradas
  • SSL/HTTPS en producción

• Deseables:

  • US-AUTH-003: Consistencia con otros OAuth

---

Definition of Ready (DoR)

• GitHub OAuth App creada
• Client ID y Secret disponibles
• Mockups aprobados
• API contract definido
• Callback URL configurada

---

Definition of Done (DoD)

• Código implementado y revisado
• Tests unitarios con 80%+ cobertura
• Tests de integración pasando
• Tests E2E implementados
• Manejo de emails privados funcional
• Documentación actualizada
• Logs implementados
• QA aprobado en staging
• Deploy a producción exitoso

---

Notas Técnicas

GitHub OAuth Flow

1. Frontend redirige a /api/v1/auth/github
2. Backend redirige a GitHub con:
   • client_id
   • redirect_uri
   • scope=user:email read:user
   • state (CSRF token)
3. Usuario autoriza en GitHub
4. GitHub redirige a redirect_uri con code
5. Backend intercambia code por access_token
6. Backend obtiene perfil: GET /user
7. Backend obtiene emails: GET /user/emails
8. Backend selecciona email primario y verificado
9. Backend crea/actualiza usuario
10. Backend genera JWT

GitHub API Endpoints

• Authorization: https://github.com/login/oauth/authorize
• Token exchange: https://github.com/login/oauth/access_token
• User profile: https://api.github.com/user
• User emails: https://api.github.com/user/emails

Email Selection Logic

// Prioridad de selección de email:
1. Email primario + verificado
2. Email primario (aunque no esté verificado)
3. Primer email verificado
4. Solicitar email adicional al usuario

Environment Variables

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
GITHUB_CALLBACK_URL=https://trading.com/api/v1/auth/github/callback

Consideraciones Especiales de GitHub

• GitHub permite múltiples emails por cuenta
• Email puede ser privado (noreply@github.com)
• Necesita dos llamadas: una para perfil, otra para emails
• Access tokens no expiran (a menos que sean revocados)
• Scopes mínimos: user:email y read:user
• Rate limit: 5000 requests/hour para usuarios autenticados

Security Considerations

• Validar state parameter (CSRF)
• Usar HTTPS en callbacks
• No almacenar access tokens sin encriptar
• Rate limiting en endpoints
• Logs de intentos de autenticación
• Validar que el email sea verificado en GitHub

---

Requerimientos Relacionados

• RF-AUTH-003: OAuth Social

Especificaciones Relacionadas

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