---
id: "US-AUTH-007"
title: "OAuth GitHub"
type: "User Story"
status: "To Do"
priority: "Media"
epic: "OQI-001"
story_points: 3
created_date: "2025-12-05"
updated_date: "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](../_MAP.md)

---

## 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`:
  ```sql
  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

```typescript
// 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

```env
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](../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)