US03 - Criar endpoint de login e logout

# Contrato REST API - Autenticação (Login/Logout)

## URL Base
```
https://api.pointtils.com/v1
```

## Autenticação
A maioria dos endpoints requer autenticação JWT. Inclua o token no cabeçalho Authorization:
```
Authorization: Bearer <jwt_token>
```

## Endpoints de Autenticação

### 1. Login
Realiza o login do usuário e retorna tokens de acesso.

**Endpoint:** `POST /auth/login`

**Corpo da Requisição:**
```json
{
  "email": "usuario@exemplo.com",
  "password": "senha123"
}
```

**Resposta:**
```json
{
  "success": true,
  "message": "Login realizado com sucesso",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "refreshExpiresIn": 86400
  }
}
```

**Respostas de Erro:**
- `400 Bad Request` - Campos obrigatórios não preenchidos
- `401 Unauthorized` - Credenciais inválidas
- `403 Forbidden` - Usuário bloqueado
- `404 Not Found` - Usuário não encontrado
- `422 Unprocessable Entity` - Formato de email inválido
- `429 Too Many Requests` - Muitas tentativas de login
- `500 Internal Server Error` - Erro inesperado

---

### 2. Refresh Token
Renova o token de acesso usando um refresh token válido.

**Endpoint:** `POST /auth/refresh`

**Corpo da Requisição:**
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Resposta:**
```json
{
  "success": true,
  "message": "Tokens renovados com sucesso",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "refreshExpiresIn": 86400
  }
}
```

**Respostas de Erro:**
- `400 Bad Request` - Refresh token não fornecido
- `401 Unauthorized` - Refresh token inválido ou expirado
- `500 Internal Server Error` - Erro inesperado

---

### 3. Logout (Implementação Cliente)
O logout é implementado no lado do cliente. Para efetuar logout:

1. Remover o token JWT do armazenamento local/sessão
2. Invalidar o refresh token no servidor (se aplicável)

**Nota:** Esta API não possui um endpoint específico para logout, pois o JWT é stateless.

---

## Endpoints de Teste JWT (Desenvolvimento)

### 4. Gerar Token Público
Gera um token de acesso público para testes.

**Endpoint:** `GET /api/jwt/public`

**Resposta:**
```
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

---

### 5. Recurso Protegido
Acessa um recurso que requer autenticação.

**Endpoint:** `GET /api/jwt/protected`

**Cabeçalho:**
```
Authorization: Bearer <jwt_token>
```

**Resposta:**
```
"Authenticated."
```

**Respostas de Erro:**
- `401 Unauthorized` - Token inválido ou não fornecido

---

### 6. Gerar Tokens (Testes)
Gera access token e refresh token para um usuário (apenas desenvolvimento).

**Endpoint:** `POST /api/jwt/generate-tokens`

**Parâmetros de Consulta:**
- `username` (string) - Nome de usuário para gerar tokens

**Resposta:**
```json
{
  "success": true,
  "message": "Tokens gerados com sucesso",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "refreshExpiresIn": 86400
  }
}
```

---

## Tipos de Dados

### Token Response
```json
{
  "accessToken": "string",
  "refreshToken": "string",
  "tokenType": "string",
  "expiresIn": 3600,
  "refreshExpiresIn": 86400
}
```

### Login Request
```json
{
  "email": "string",
  "password": "string"
}
```

### Refresh Token Request
```json
{
  "refresh_token": "string"
}
```

## Formato de Resposta de Erro
```json
{
  "success": false,
  "message": "Descrição da mensagem de erro",
  "data": null
}
```

## Códigos de Status
- `200 OK` - Requisição bem-sucedida
- `201 Created` - Recurso criado com sucesso
- `400 Bad Request` - Parâmetros de requisição inválidos
- `401 Unauthorized` - Autenticação necessária ou inválida
- `403 Forbidden` - Permissões insuficientes
- `404 Not Found` - Recurso não encontrado
- `422 Unprocessable Entity` - Dados inválidos para processamento
- `429 Too Many Requests` - Muitas requisições em curto período
- `500 Internal Server Error` - Erro do servidor

## Limitação de Taxa para Login
- Máximo 5 tentativas de login por minuto por endereço IP
- Bloqueio temporário após 5 tentativas falhas consecutivas
- Bloqueio permanente após múltiplas violações

## Segurança
- Tokens JWT com expiração configurável
- Refresh tokens com vida útil mais longa
- Validação de formato de email
- Proteção contra força bruta
- Headers de segurança HTTP

## Exemplos de Uso

### Exemplo 1: Login
```bash
curl -X POST "https://api.pointtils.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@exemplo.com",
    "password": "senha123"
  }'
```

### Exemplo 2: Refresh Token
```bash
curl -X POST "https://api.pointtils.com/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'
```

### Exemplo 3: Acessar Recurso Protegido
```bash
curl -X GET "https://api.pointtils.com/api/jwt/protected" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Versionamento
Esta API é a versão 1. Todos os endpoints são prefixados com `/v1/` ou `/api/`.

## Notas Importantes
1. Os endpoints `/api/jwt/` são para desenvolvimento e testes
2. Em produção, considere implementar blacklist de tokens para logout
3. Mantenha os tokens seguros e não os exponha publicamente
4. Use HTTPS em produção para proteger as credenciais
5. Implemente validação adicional no cliente para melhor UX

## Configurações de Segurança

### Tokens JWT
- **Access Token**: 1 hora de validade
- **Refresh Token**: 24 horas de validade
- **Algoritmo**: HS256 (HMAC SHA-256)
- **Blacklist**: Tokens invalidados armazenados até expiração

### Rate Limiting
- **Login**: 5 tentativas por IP a cada 15 minutos
- **Refresh**: 10 tentativas por token a cada hora
- **Validate**: 100 tentativas por IP a cada hora

### Headers de Segurança
```
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
```

---

## Fluxo de Autenticação

### 1. Login Inicial
```
Cliente → POST /auth/login
Servidor ← 200 OK + {access_token, refresh_token}
```

### 2. Requisições Autenticadas
```
Cliente → GET /api/recurso + Authorization: Bearer {access_token}
Servidor ← 200 OK + dados
```

### 3. Token Expirado
```
Cliente → GET /api/recurso + Authorization: Bearer {access_token_expired}
Servidor ← 401 Unauthorized + "TOKEN_EXPIRED"
```

### 4. Refresh Token
```
Cliente → POST /auth/refresh + {refresh_token}
Servidor ← 200 OK + {novo_access_token, novo_refresh_token}
```

### 5. Refresh Token Inválido
```
Cliente → POST /auth/refresh + {refresh_token_invalid}
Servidor ← 401 Unauthorized + "INVALID_REFRESH_TOKEN"
Cliente → Redireciona para login
```

US03 - Criar endpoint de login e logout #35

Description

Contrato REST API - Autenticação (Login/Logout)

URL Base

Autenticação

Endpoints de Autenticação

1. Login

2. Refresh Token

3. Logout (Implementação Cliente)

Endpoints de Teste JWT (Desenvolvimento)

4. Gerar Token Público

5. Recurso Protegido

6. Gerar Tokens (Testes)

Tipos de Dados

Token Response

Login Request

Refresh Token Request

Formato de Resposta de Erro

Códigos de Status

Limitação de Taxa para Login

Segurança

Exemplos de Uso

Exemplo 1: Login

Exemplo 2: Refresh Token

Exemplo 3: Acessar Recurso Protegido

Versionamento

Notas Importantes

Configurações de Segurança

Tokens JWT

Rate Limiting

Headers de Segurança

Fluxo de Autenticação

1. Login Inicial

2. Requisições Autenticadas

3. Token Expirado

4. Refresh Token

5. Refresh Token Inválido

Sub-issues

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions