🔐 node-api-starter

Boilerplate de API REST em produção com TypeScript — autenticação JWT (access + refresh), RBAC, validação, Swagger, testes e Docker.

---

📌 Sobre

Um ponto de partida pronto para produção para APIs Node.js — resolvendo as partes que toda empresa precisa e ninguém quer reescrever: autenticação, autorização por papéis, validação de entrada, documentação e testes. Arquitetura em camadas e repositório plugável (troque memória → PostgreSQL sem mexer nos serviços).

✨ O que vem pronto

• 🔑 Autenticação JWT com access + refresh token e rotação + revogação (logout)
• 🛡️ RBAC — autorização por papéis (ADMIN, USER)
• 🔒 Senhas com bcrypt
• 🪖 Helmet (headers de segurança) + CORS por origem configurável
• 🚦 Rate limiting nas rotas de autenticação (express-rate-limit)
• ✅ Validação de entrada com Zod (erros 400 estruturados)
• 📚 Swagger UI em /docs (OpenAPI 3)
• 🧪 20 testes de integração (Vitest + Supertest)
• 🐳 Docker + docker-compose (com PostgreSQL)
• ⚙️ CI no GitHub Actions (typecheck + testes + build)
• 🧱 Arquitetura modular (config, lib, middleware, modules)

🔗 Endpoints

Método	Rota	Auth	Descrição
POST	/api/auth/register	—	Cria conta (retorna tokens)
POST	/api/auth/login	—	Login (retorna tokens)
POST	/api/auth/refresh	—	Renova e rotaciona os tokens
POST	/api/auth/logout	—	Revoga o refresh token informado
GET	/api/auth/me	Bearer	Dados do usuário logado
GET	/api/users	ADMIN	Lista usuários
GET	/api/users/:id	ADMIN	Detalhe
PATCH	/api/users/:id	ADMIN	Atualiza
DELETE	/api/users/:id	ADMIN	Remove
GET	/health · /docs	—	Status · Documentação

🚀 Como rodar

npm install
cp .env.example .env   # gere segredos JWT fortes: openssl rand -hex 32
npm run dev        # http://localhost:3000  (docs em /docs)
npm test           # 20 testes de integração
npm run build      # bundle de produção (tsup)

⚠️ Segredos JWT são obrigatórios. Em production a aplicação falha ao iniciar se JWT_ACCESS_SECRET/JWT_REFRESH_SECRET estiverem ausentes, com menos de 32 caracteres ou usando placeholders conhecidos. Em dev/test, um segredo efêmero é gerado automaticamente (com aviso) e os tokens são invalidados a cada reinício.

🔑 Admin (seed opcional)

Não há admin pré-cadastrado por padrão. Para semear um, defina no .env:

SEED_ADMIN=true
SEED_ADMIN_EMAIL=admin@example.com
SEED_ADMIN_PASSWORD=uma-senha-forte

O seed é ignorado quando SEED_ADMIN não é true, e as credenciais nunca são impressas em produção.

🔁 Refresh tokens (rotação + revogação)

/api/auth/refresh valida o refresh token, invalida o token usado e emite um novo par (rotação). Reutilizar um refresh token já rotacionado retorna 401. /api/auth/logout revoga o refresh token informado. Os jti válidos ficam num store em memória que, como o repositório de usuários, é reiniciado a cada restart do processo — troque por Redis/banco numa implementação real.

Com Docker

docker compose up --build   # ajuste os segredos JWT no docker-compose.yml antes

Exemplo

# login (use as credenciais do seu seed, se habilitado)
curl -X POST localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"uma-senha-forte"}'

# usar o token
curl localhost:3000/api/auth/me -H "Authorization: Bearer <accessToken>"

🗄️ Banco de dados real (PostgreSQL + Prisma)

O projeto usa um repositório em memória por padrão (zero setup). Para produção, há um prisma/schema.prisma pronto:

1. npm i @prisma/client && npm i -D prisma
2. Configure DATABASE_URL no .env
3. npx prisma migrate dev
4. Implemente UserRepository (src/db/repository.ts) usando o Prisma Client

A interface UserRepository garante que nenhum serviço precisa mudar.

🧱 Estrutura

src/
├── env.ts                 # variáveis validadas com Zod
├── app.ts / server.ts     # app Express + bootstrap
├── lib/                   # jwt, password, errors
├── db/repository.ts       # camada de dados (plugável)
├── middleware/            # auth, authorize (RBAC), validate, errors
├── modules/auth/          # register, login, refresh, me
├── modules/users/         # CRUD com RBAC
└── docs/openapi.ts        # spec OpenAPI

📄 Licença

MIT © Samuel Ferreira

---

GitHub · LinkedIn