rckrdmrd
a7cca885f0
Changes include: - Updated architecture documentation - Enhanced module definitions (OQI-001 to OQI-008) - ML integration documentation updates - Trading strategies documentation - Orchestration and inventory updates - Docker configuration updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
320 lines
11 KiB
Markdown
320 lines
11 KiB
Markdown
---
|
|
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 OrbiQuant
|
|
**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 OrbiQuant │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ 📧 Email │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ 🔴 Continuar con Google │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ [Facebook] [Twitter/X] [Apple] │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ ⚫ Continuar con GitHub │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
|
Ventana de GitHub OAuth:
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ github.com ✕ │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Authorize OrbiQuant │
|
|
│ │
|
|
│ OrbiQuant by OrbiQuant 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://orbiquant.com/api/v1/auth/github/callback │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ Authorize OrbiQuant │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ 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://orbiquant.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)
|