Trabalhando com tokens JWT em TypeScript: biblioteca jsonwebtoken e guia completo

Tokens JWT em TypeScript: guia completo com a biblioteca jsonwebtoken

\n\n

JSON Web Token (JWT) é um padrão aberto (RFC 7519) para criação de tokens de acesso baseados no formato JSON. JWT é amplamente utilizado para autenticação e troca de informações entre cliente e servidor. Em TypeScript, graças à tipagem estrita, trabalhar com JWT se torna especialmente conveniente e seguro. Neste artigo, veremos como usar a biblioteca popular jsonwebtoken em TypeScript para criar, verificar e gerenciar tokens JWT.

\n\n

Instalação e configuração

\n\n

Para começar, instale os pacotes necessários:

\n\n

npm install jsonwebtoken\nnpm install -D @types/jsonwebtoken

\n\n

O primeiro pacote é a própria biblioteca, o segundo são os tipos TypeScript para ela. Após a instalação, crie um arquivo jwt.service.ts onde armazenaremos toda a lógica de trabalho com tokens.

\n\n

Criação de token JWT

\n\n

A função principal do jsonwebtoken é sign(). Vejamos seu uso com tipagem:

\n\n

import jwt from 'jsonwebtoken';\n\ninterface TokenPayload {\n  userId: number;\n  email: string;\n  role: 'user' | 'admin';\n}\n\nconst createAccessToken = (payload: TokenPayload): string => {\n  const secret = process.env.JWT_SECRET || 'default_secret';\n  const options: jwt.SignOptions = {\n    expiresIn: '15m', // token válido por 15 minutos\n    algorithm: 'HS256',\n  };\n\n  return jwt.sign(payload, secret, options);\n};

\n\n

Importante: nunca armazene a chave secreta no código. Use variáveis de ambiente (arquivo .env).

\n\n

Verificação e decodificação do token

\n\n

Para verificar a autenticidade do token, use a função verify(). Ela verifica automaticamente a assinatura e a validade:

\n\n

const verifyToken = (token: string): TokenPayload => {\n  const secret = process.env.JWT_SECRET || 'default_secret';\n\n  try {\n    const decoded = jwt.verify(token, secret) as TokenPayload;\n    return decoded;\n  } catch (error) {\n    if (error instanceof jwt.TokenExpiredError) {\n      throw new Error('Token expirado');\n    }\n    if (error instanceof jwt.JsonWebTokenError) {\n      throw new Error('Token inválido');\n    }\n    throw error;\n  }\n};

\n\n

Observe a conversão de tipo as TokenPayload — isso garante que o TypeScript conheça a estrutura dos dados decodificados.

\n\n

Refresh-tokens: extensão da sessão

\n\n

Na prática, os access-tokens têm vida curta (15-30 minutos), por isso é necessário um mecanismo para renová-los. Para isso, usa-se um refresh-token com maior tempo de vida:

\n\n

const createRefreshToken = (payload: TokenPayload): string => {\n  const secret = process.env.JWT_REFRESH_SECRET || 'refresh_secret';\n  const options: jwt.SignOptions = {\n    expiresIn: '7d', // uma semana\n    algorithm: 'HS256',\n  };\n\n  return jwt.sign(payload, secret, options);\n};\n\nconst refreshAccessToken = (refreshToken: string): string => {\n  const secret = process.env.JWT_REFRESH_SECRET || 'refresh_secret';\n\n  try {\n    const decoded = jwt.verify(refreshToken, secret) as TokenPayload;\n    // Pode verificar se o refresh-token não foi revogado no banco de dados\n    return createAccessToken({\n      userId: decoded.userId,\n      email: decoded.email,\n      role: decoded.role,\n    });\n  } catch {\n    throw new Error('Refresh-token inválido');\n  }\n};

\n\n

Middleware para Express em TypeScript

\n\n

A integração do JWT com Express.js requer a criação de um middleware. Aqui está uma versão tipada:

\n\n

import { Request, Response, NextFunction } from 'express';\n\ninterface AuthRequest extends Request {\n  user?: TokenPayload;\n}\n\nconst authMiddleware = (req: AuthRequest, res: Response, next: NextFunction) => {\n  const authHeader = req.headers.authorization;\n\n  if (!authHeader || !authHeader.startsWith('Bearer ')) {\n    return res