🔐 @devflow-modules/jwt-auth

Módulo de autenticação JWT seguro, modular e reutilizável para aplicações Node.js. Oferece suporte completo a:

• ✅ Access Token
• 🔁 Refresh Token
• 🔑 Hash e verificação de senhas
• 🛡️ Middleware de proteção de rotas
• 🧪 Testes com cobertura
• 🚫 Zero dependência de banco de dados

📦 Requisitos

• Node.js >= 16
• npm >= 8

🚀 Instalação

npm install @devflow-modules/jwt-auth

Para uso local com desenvolvimento:

npm link

📆 Variáveis de ambiente

Crie um arquivo .env com:

JWT_SECRET=chave_secreta_access_token
JWT_EXPIRES_IN=1h
JWT_REFRESH_SECRET=chave_secreta_refresh_token
JWT_REFRESH_EXPIRES_IN=7d

🔧 Suporte a múltiplos algoritmos JWT

Este módulo suporta algoritmos simétricos (HS256, HS512) e assimétricos (RS256) para assinar/verificar tokens JWT.

✅ Configuração via .env

# Algoritmo padrão (HS256, HS512 ou RS256)
JWT_ALGORITHM=HS256

# Para algoritmos HS256 / HS512
JWT_SECRET=your_hmac_secret

# Para RS256 (criptografia com chave pública/privada)
JWT_PRIVATE_KEY_PATH=src/keys/private.key
JWT_PUBLIC_KEY_PATH=src/keys/public.key

🔐 Gerar chaves para RS256

Se você optar por usar RS256, gere suas chaves com:

openssl genrsa -out src/keys/private.key 2048
openssl rsa -in src/keys/private.key -pubout -out src/keys/public.key

💡 As chaves devem ser referenciadas corretamente nas variáveis JWT_PRIVATE_KEY_PATH e JWT_PUBLIC_KEY_PATH.

✅ Exemplo de uso (sem alterações no código)

A mesma API funciona com qualquer algoritmo:

const { signToken, verifyToken } = require('@devflow-modules/jwt-auth');

const token = signToken({ id: '123' });
const decoded = verifyToken(token);

✅ Funcionalidades

🔐 Geração e Verificação de Access Token

// CommonJS
const { signToken, verifyToken } = require('@devflow-modules/jwt-auth');

// ESModules (futuro)
import { signToken, verifyToken } from '@devflow-modules/jwt-auth';

const token = signToken({ id: '123', role: 'admin' });
const payload = verifyToken(token);
// { id: '123', role: 'admin', iat, exp }

🔁 Geração e Verificação de Refresh Token

const { signRefreshToken, verifyRefreshToken } = require('@devflow-modules/jwt-auth');

const refresh = signRefreshToken({ id: '123' });
const payload = verifyRefreshToken(refresh);

🔑 Hash e Verificação de Senhas

const { hashPassword, comparePassword } = require('@devflow-modules/jwt-auth');

const hash = await hashPassword('minhasenha');
const isValid = await comparePassword('minhasenha', hash); // true ou false

🛡️ Middleware: protectRoute (Express)

Protege rotas de acesso não autenticado.

const express = require('express');
const { protectRoute } = require('@devflow-modules/jwt-auth');

const app = express();

app.get('/private', protectRoute, (req, res) => {
  res.json({ user: req.user });
});

🛡️ Middleware: protectWithRoles (Express)

Protege rotas com base em roles (funções/permissões) do usuário autenticado.

const express = require('express');
const { protectWithRoles } = require('@devflow-modules/jwt-auth');

const app = express();

// Permite acesso apenas para usuários com role 'admin' ou 'editor'
app.get('/admin', protectWithRoles(['admin', 'editor']), (req, res) => {
  res.json({ message: 'Acesso permitido para administradores e editores.' });
});

// Permite acesso apenas para usuários com role 'user'
app.get('/profile', protectWithRoles(['user']), (req, res) => {
  res.json({ message: 'Acesso permitido para usuários.' });
});

💻 Exemplo completo (Express)

require('dotenv').config();
const express = require('express');
const { signToken, signRefreshToken, protectRoute } = require('@devflow-modules/jwt-auth');

const app = express();
app.use(express.json());

// login (gera access e refresh token)
app.post('/login', (req, res) => {
  const token = signToken({ id: 'user123' });
  const refresh = signRefreshToken({ id: 'user123' });
  res.json({ token, refresh });
});

app.get('/private', protectRoute, (req, res) => {
  res.json({ user: req.user });
});

app.listen(3000, () => console.log('API rodando em http://localhost:3000'));

🧪 Testes

Execute os testes com cobertura:

npm run test:coverage

💡 Pré-push protegido com Husky

Este repositório usa Husky para impedir git push com testes quebrados ou cobertura insuficiente.

🧱 Estrutura

src/
├── jwt/
│   ├── signToken.cjs
│   ├── verifyToken.cjs
│   ├── signRefreshToken.cjs
│   └── verifyRefreshToken.cjs
├── password/
│   ├── hashPassword.cjs
│   └── comparePassword.cjs
├── middleware/
│   ├── protectRoute.cjs
│   └── protectWithRoles.cjs      # Novo middleware adicionado
│   └── protectRouteFromCookie.cjs
├── utils/
│   └── env.cjs
├── index.js
tests/
├── cookies/
│   └── cookies.test.cjs
├── jwt/
│   ├── jwt.test.cjs
│   ├── jwtAlgorithm.test.cjs
│   ├── refreshToken.test.cjs
│   ├── signToken.errors.test.cjs
│   └── verifyToken.errors.test.cjs
├── middleware/
│   ├── middleware.test.cjs
│   ├── protectWithRoles.test.cjs   # Testes do middleware de roles
│   └── protectRouteFromCookie.test.cjs
├── password/
│   └── password.test.cjs

🍪 Uso com Cookies

Você pode definir e extrair tokens via cookies para sessões seguras com HTTP-only:

const { setTokenCookie, getTokenFromCookie } = require('@devflow-modules/jwt-auth');

setTokenCookie(res, 'meu_token'); // Define cookie "jwt"
const token = getTokenFromCookie(req); // Extrai token do cookie

Com middleware:

const { protectRouteFromCookie } = require('@devflow-modules/jwt-auth');
app.get('/private', protectRouteFromCookie, (req, res) => {
  res.json({ user: req.user });
});

📌 Roadmap

• [X] Suporte a múltiplos algoritmos JWT (HS512, RS256)
• [X] Suporte a cookies HTTP-only
• [X] Middleware para roles e permissões
• [X] Changelog automatizado + GitHub Release
• [ ] Exemplo completo com autenticação + refresh
• [ ] Middleware opcional para rotas públicas
• [ ] Compatibilidade com ESM (import/export)
• [ ] Suporte a sessão baseada em token com blacklist
• [ ] Integração com login social (Google, GitHub)

⚖️ Licença

MIT © devflow-modules