pygmy

Visão geral

pygmy nasceu de um problema que se repetia: cada projeto precisava de verificação por código no e-mail, e reescrever isso toda vez é desperdício e fonte de erro. Em vez disso, extraí o serviço para uma API única, que qualquer projeto consome com uma chave. O backend é FastAPI com Redis: gera o código, envia por SMTP e valida com limites rígidos. O site em Next.js traz documentação, uma demo interativa e um painel /admin, protegido por login com GitHub, onde crio uma credencial por projeto, giro as chaves e acompanho o uso dos últimos 14 dias. Tudo sobe com um docker compose em uma VPS, isolado de outros serviços, atrás de Caddy com HTTPS automático. É a versão enxuta, de código aberto, do mesmo tipo de serviço de OTP que construí profissionalmente.

Stack

• Python
• FastAPI
• Redis
• Pydantic
• Next.js
• TypeScript
• GitHub OAuth
• SMTP
• Docker
• Docker Compose
• Caddy
• pytest

Principais entregas

• Dois endpoints, POST /v1/otp/request e /verify, autenticados por Bearer token ou X-API-Key, com exemplos em curl, Python e Node
• Códigos de 6 dígitos gerados com secrets, guardados no Redis apenas como HMAC, com expiração de 5 minutos e uso único
• Limites contra abuso: 5 tentativas por código, cooldown de 60 s para reenvio, 5 pedidos por hora por e-mail e 20 por hora por IP do usuário final
• Uma credencial por projeto, com namespace isolado: o mesmo e-mail em dois projetos nunca compartilha código nem limites
• Chaves guardadas só como SHA-256; o segredo pyg_... aparece uma única vez, na criação ou na rotação
• Painel /admin com login somente por GitHub (OAuth, lista de usuários permitidos) para criar, renomear, desativar, girar e excluir chaves, com gráfico de uso dos últimos 14 dias
• Envio por SMTP (Hostinger) com template HTML do e-mail e nome do app configurável por requisição
• Deploy isolado: rede, volume e containers próprios, portas só em 127.0.0.1, limites de memória e CPU, Caddy ou nginx na frente
• Testes automatizados com pytest

Desafios técnicos

• 01

  Tratar o OTP como dado sensível: guardar só o HMAC, comparar em tempo constante e garantir o uso único mesmo com verificações simultâneas

• 02

  Aplicar rate limit e cooldown de forma atômica no Redis, sem corridas entre requisições concorrentes

• 03

  Isolar os projetos entre si, usando o id da chave, e não o nome, como namespace, para que renomear nunca quebre nada

• 04

  Proteger o painel: o navegador nunca vê a chave admin, que fica só no servidor do site, e a sessão é um cookie httpOnly

• 05

  Evitar que um código fique preso quando o e-mail não é entregue, removendo o código e o cooldown se o envio falhar

• 06

  Conviver na mesma VPS com outros serviços, sem disputar portas nem recursos