Isatec-jwt

Lib JWT minimalista para Node.js. Zero dependências, ES Module, focada em performance e DX.

Instalação

npm install isatec-jwt

Requer Node.js >= 18.

Uso

import jwt from 'isatec-jwt'

// Gerar token
const token = jwt.encode({ id: 1, nome: 'Carlos' }, 'meu-secret', '30m')

// Decodificar e validar
try {
  const user = jwt.decode(token, 'meu-secret')
  console.log(user) // { id: 1, nome: 'Carlos' }
} catch (e) {
  console.error(e.message)
}

API

jwt.encode(payload, secret, exp?)

Gera um token JWT assinado com HMAC-SHA256.

| Parâmetro | Tipo | Padrão | Descrição | |---|---|---|---| | payload | object | — | Dados a serem codificados no token | | secret | string | — | Chave secreta para assinatura | | exp | string | "1h" | Tempo de expiração do token |

Formatos de expiração:

| Valor | Significado | |---|---| | "15s" | 15 segundos | | "30m" | 30 minutos | | "1h" | 1 hora (padrão) | | "7d" | 7 dias |

O encode adiciona automaticamente iat (data de criação) e exp (data de expiração) ao payload. Esses campos são removidos no decode.

Retorna: string — token JWT.

const token = jwt.encode({ id: 42, cargo: 'admin' }, 'secret', '2h')

jwt.decode(token, secret)

Decodifica um token JWT, valida a assinatura e checa a expiração.

| Parâmetro | Tipo | Descrição | |---|---|---| | token | string | Token JWT gerado pelo encode | | secret | string | Mesma chave secreta usada no encode |

Retorna: object — payload original (sem iat e exp).

Lança erros com mensagens em português:

| Mensagem | Quando | |---|---| | "Token mal formatado" | Token não tem 3 partes separadas por ponto | | "Algoritmo de assinatura não suportado" | Header com alg diferente de HS256 | | "Assinatura inválida" | Secret incorreto ou token alterado | | "Token sem campo de expiração" | Payload não contém exp | | "Token expirado" | Tempo de expiração já passou | | Formato de expiração inválido: "..." | exp com formato desconhecido no encode |

try {
  const user = jwt.decode(token, 'secret')
} catch (e) {
  if (e.message === 'Token expirado') {
    // redirecionar para login
  }
  if (e.message === 'Assinatura inválida') {
    // token adulterado
  }
}

Exemplo com Express

import express from 'express'
import jwt from 'isatec-jwt'

const app = express()
const SECRET = process.env.JWT_SECRET

app.post('/login', (req, res) => {
  const user = authenticate(req.body)
  if (!user) return res.status(401).json({ erro: 'Credenciais inválidas' })

  const token = jwt.encode({ id: user.id, email: user.email }, SECRET, '1d')
  res.json({ token })
})

app.get('/perfil', (req, res) => {
  try {
    const user = jwt.decode(req.headers.authorization?.slice(7), SECRET)
    res.json(user)
  } catch (e) {
    res.status(401).json({ erro: e.message })
  }
})

app.listen(3000)

Características

• Zero dependências — usa apenas node:crypto
• HS256 — HMAC com SHA-256
• timingSafeEqual — proteção contra timing attacks na comparação de assinatura
• Header cacheado — codificado uma única vez
• ES Module — import/export nativo
• JSDoc em português — autocomplete no editor sem build step

Testes

npm test