FastAPI Secured API

API minimalista, segura e completa desenvolvida com FastAPI utilizando SQLite, Argon2 e criptografia HTTPS nativa.

---

🛠️ Tecnologias Utilizadas

---

📋 Sobre o Projeto

Este projeto consiste em uma API minimalista, segura e completa que demonstra o uso de FastAPI para controle de acessos com dois perfis de usuários (Admin e User). O banco de dados local utiliza SQLite e as senhas são criptografadas com Argon2-cffi, garantindo proteção moderna contra força bruta. Os endpoints de CRUD e rotas protegidas são autenticados via JWT sob uma conexão obrigatória HTTPS.

🗂️ Estrutura de Pastas e Arquivos

• main.py: Ponto de entrada do FastAPI, definindo rotas, autenticação, controle de permissões e ciclo de vida (lifespan).
• database.py: Configuração do SQLAlchemy e sessão do banco de dados SQLite.
• models.py: Definição do modelo de banco de dados do User.
• schemas.py: Esquemas de validação do Pydantic para entradas e saídas.
• security.py: Lógica de hash de senhas com Argon2 e emissão/leitura de tokens JWT.
• certificates.py: Script auxiliar para gerar certificados SSL autoassinados (cert.pem, key.pem) para testes locais em HTTPS.
• run.py: Script de inicialização que garante a presença dos certificados SSL e executa o servidor Uvicorn.
• test_main.py: Suíte de testes automatizados unitários e de integração utilizando pytest e httpx2.
• Dockerfile & .dockerignore: Receita para empacotar a aplicação em uma imagem Alpine 3.20 leve que roda sob usuário não-privilegiado.
• .env & .env.example: Arquivo de configurações locais e modelo com as variáveis de ambiente necessárias.

---

🚀 Instalação e Execução

Pré-requisitos

• Ter o gerenciador de pacotes UV instalado no sistema.

Passo 1: Configurar Variáveis de Ambiente

Copie o arquivo de exemplo para criar seu .env local:

# No Windows (PowerShell)
Copy-Item .env.example .env

# No Linux / macOS / Git Bash
cp .env.example .env

E ajuste os valores no .env caso queira mudar as configurações locais (como ativar ou desativar o modo DEBUG).

Passo 2: Executar o Projeto

O uv gerencia o ambiente virtual automaticamente. Para executar o servidor de desenvolvimento:

uv run run.py

Isso fará com que o uv:

1. Crie a pasta ssl/ e gere automaticamente os arquivos cert.pem e key.pem se eles não existirem.
2. Crie o banco de dados fastapi_secured_api.db e crie as tabelas se não existirem.
3. Se o banco estiver vazio, semeará uma conta Admin padrão inicial:
   • Username: admin
   • Password: adminpassword123
   • Email: admin@example.com
4. Inicie o servidor Uvicorn rodando em https://localhost:8000 com auto-reload ativado.

---

🧪 Executando os Testes

Para executar a suíte de testes unitários e de integração (que rodam de forma isolada em um banco de dados SQLite em memória):

uv run pytest

---

🛣️ Rotas da API

Públicas

• GET /health: Retorna o status da aplicação e a integridade da conexão com o banco de dados.
• POST /token: Recebe credenciais de login via form-data (username e password) e retorna o JWT access token.

Protegidas (Requer Autenticação)

• GET /secured: Endpoint restrito a usuários autenticados (User e Admin), respondendo com uma mensagem contendo as informações do seu perfil logado.
• GET /users/me: Retorna os dados do próprio usuário autenticado.
• PUT /users/me: Atualiza dados do próprio usuário. Usuários comuns são impedidos de alterar seus cargos (role) ou status de atividade (is_active).

Protegidas (Requer privilégios de Administrador)

• GET /users: Lista todos os usuários cadastrados.
• POST /users: Cria novos usuários (comum ou administrador).
• GET /users/{user_id}: Busca detalhes de um usuário específico por ID.
• PUT /users/{user_id}: Atualiza qualquer campo de qualquer usuário (incluindo role e is_active). Impede que o próprio admin logado se desative ou se rebaixe de cargo.
• PATCH /users/{user_id}/promote: Promove o usuário especificado diretamente para o cargo de admin.
• DELETE /users/{user_id}: Deleta permanentemente um usuário. Impede a autoexclusão de um admin logado.

---

🧪 Exemplos de Testes com cURL

Como o servidor roda sob HTTPS autoassinado, use a flag -k ou --insecure nas chamadas cURL para aceitar o certificado local:

1. Obter Token de Autenticação (Login)

curl -k -X POST https://localhost:8000/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=adminpassword123"

2. Acessar Rota Segura (Substitua <TOKEN> pelo JWT retornado)

curl -k https://localhost:8000/secured \
  -H "Authorization: Bearer <TOKEN>"

3. Criar um Novo Usuário (Admin)

curl -k -X POST https://localhost:8000/users \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "joaosilva",
    "email": "joao@example.com",
    "password": "senhaSegura123",
    "role": "user"
  }'

---

🛡️ Documentação Interativa da API (Swagger / OpenAPI)

Uma vez que o servidor estiver rodando, você pode acessar a documentação interativa e testar as chamadas diretamente do navegador:

• Swagger UI: https://localhost:8000/docs
• ReDoc: https://localhost:8000/redoc

Nota: Por se tratar de um certificado autoassinado, o navegador exibirá um alerta de segurança (ex: "Sua conexão não é particular"). Você pode clicar em "Avançado" e prosseguir para acessar a interface do Swagger com segurança.

---

🐳 Executando com Docker

1. Construir a Imagem Docker

docker build -t fastapi-secured-api .

2. Executar o Container

Para rodar a aplicação mapeando a porta 8000:

docker run -d --name fastapi_api -p 8000:8000 fastapi-secured-api

Se desejar persistir o banco de dados e os certificados gerados localmente na sua máquina, mapeie os volumes correspondentes:

# No Windows (PowerShell)
docker run -d --name fastapi_api -p 8000:8000 -v ${PWD}/ssl:/app/ssl -v ${PWD}:/app/data fastapi-secured-api

---

👤 Desenvolvedor

• Nome: Roberto Lins
• E-mail: robertolins1979@gmail.com

---

⚖️ Licença

Este projeto é de código aberto e está licenciado sob os termos da licença MIT.