JWT - Documentação Azion

O pacote @aziontech/jwt é a biblioteca da Azion Lib para JSON Web Tokens (JWTs). As três funções dele assinam um payload em um token, verificam um token e retornam o payload dele, e decodificam um token sem conferir a assinatura. Elas não fazem chamadas de API e não precisam de token. Cada função retorna o resultado diretamente ou lança um erro.

Instale o pacote:

npm install @aziontech/jwt

Os exemplos desta página são módulos ES em TypeScript que usam await no nível superior, e eles rodam no Node.js. Eles importam tipos com import type, o que mantém os exemplos carregáveis quando as anotações de tipo são removidas.

Chaves e algoritmos

O parâmetro alg de sign e verify indica o algoritmo de assinatura. O padrão dele é HS256. As declarações de tipo listam 13 valores: HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512 e EdDSA.

Uma chave é uma SignatureKey: uma string, uma JsonWebKey ou uma CryptoKey. A chave que você passa depende do algoritmo:

Com o padrão HS256, a chave é um segredo compartilhado. Assine e verifique com a mesma string.
Um algoritmo assimétrico, como RS256, recebe uma CryptoKey ou uma JsonWebKey. Assine com a chave privada e verifique com a chave pública.

Este exemplo gera um par de chaves RSA com crypto.subtle, assina um token com RS256, exibe o cabeçalho do token e verifica o token com a chave pública:

TypeScript

01import { sign, verify } from '@aziontech/jwt';

03// Asymmetric algorithms take a CryptoKey (or JsonWebKey): sign with the private key, verify with the public key

04const { privateKey, publicKey } = (await crypto.subtle.generateKey(

05 { name: 'RSASSA-PKCS1-v1_5', modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: 'SHA-256' },

06 true,

07 ['sign', 'verify'],

08)) as CryptoKeyPair;

10const token = await sign({ userId: 123 }, privateKey, 'RS256');

11console.log('header:', JSON.parse(atob(token.split('.')[0])));

12console.log('verified payload:', await verify(token, publicKey, 'RS256'));

Saída:

Texto

01header: { alg: 'RS256', typ: 'JWT' }

02verified payload: { userId: 123 }

sign

Assina um payload e retorna o token.

function sign(payload: JWTPayload, privateKey: SignatureKey, alg?: SignatureAlgorithm): Promise<string>;

Parâmetro	Tipo	Obrigatório	Descrição
`payload`	`JWTPayload`	Sim	Os claims a assinar.
`privateKey`	`SignatureKey`	Sim	A chave que assina o token: o segredo compartilhado com `HS256`, ou a chave privada com um algoritmo assimétrico.
`alg`	`SignatureAlgorithm`	Não	O algoritmo de assinatura. Padrão: `HS256`.

Retorna uma promise que resolve para o token assinado. Um valor de alg fora da lista em Chaves e algoritmos rejeita com JwtAlgorithmNotImplemented.

Este exemplo assina, com o padrão HS256, um payload que expira em uma hora:

TypeScript

01import { sign } from '@aziontech/jwt';

02import type { JWTPayload } from '@aziontech/jwt';

04const secret: string = 'your-secret-key'; // HS256 (the default) signs with a shared secret

05const payload: JWTPayload = { userId: 123, exp: Math.floor(Date.now() / 1000) + 3600 }; // 1 hour expiration

06sign(payload, secret).then((token: string) => console.log(token)); // Outputs the signed JWT

Saída:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywiZXhwIjoxNzkxMTI1NjA0fQ.mmn-otq04QJJHbUQvm_e7b0SvNUQI98CtypKEz58kDQ

verify

Confere a assinatura e os claims de tempo de um token e retorna o payload dele.

function verify(token: string, publicKey: SignatureKey, alg?: SignatureAlgorithm): Promise<JWTPayload>;

Parâmetro	Tipo	Obrigatório	Descrição
`token`	`string`	Sim	O token a verificar.
`publicKey`	`SignatureKey`	Sim	A chave que confere a assinatura: o segredo compartilhado com `HS256`, ou a chave pública com um algoritmo assimétrico.
`alg`	`SignatureAlgorithm`	Não	O algoritmo com que o token foi assinado. Padrão: `HS256`.

Retorna uma promise que resolve para o JWTPayload de um token válido. A promise rejeita quando a assinatura não corresponde à chave, quando exp está no passado, quando nbf ou iat está no futuro, ou quando o token ou o cabeçalho dele não é válido. Cada caso tem o próprio nome de erro, listado em Erros.

Este exemplo assina um token, verifica o token com o mesmo segredo e depois verifica o token com um segredo diferente:

TypeScript

01import { sign, verify } from '@aziontech/jwt';

02import type { JWTPayload } from '@aziontech/jwt';

04const secret: string = 'your-secret-key';

05const token: string = await sign({ userId: 123, exp: Math.floor(Date.now() / 1000) + 3600 }, secret);

07try {

08 const payload: JWTPayload = await verify(token, secret);

09 console.log(payload); // Outputs the payload if verification is successful

10} catch (err) {

11 console.error((err as Error).name, (err as Error).message);

12}

14try {

15 await verify(token, 'another-secret');

16} catch (err) {

17 console.error((err as Error).name, (err as Error).message); // A wrong key rejects with JwtTokenSignatureMismatched

18}

Saída:

Texto

01{ userId: 123, exp: 1791127003 }

JwtTokenSignatureMismatched token(eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywiZXhwIjoxNzkxMTI3MDAzfQ.myf2vixa4QI6GQCxHu6h5t3UpZwMya3J1UIr2W3d8pU) signature mismatched

decode

Lê o cabeçalho e o payload de um token sem verificar a assinatura dele.

function decode(token: string): { header: TokenHeader; payload: JWTPayload };

Parâmetro	Tipo	Obrigatório	Descrição
`token`	`string`	Sim	O token a decodificar.

Retorna um objeto com o TokenHeader em header e o JWTPayload em payload. A função é síncrona. Uma string que não é um JWT lança JwtTokenInvalid. Como decode não confere a assinatura, use verify antes de confiar em um claim.

O pacote não exporta TokenHeader, então o exemplo deixa o TypeScript inferir o tipo do resultado:

TypeScript

01import { sign, decode } from '@aziontech/jwt';

03const token: string = await sign({ userId: 123 }, 'your-secret-key');

04const { header, payload } = decode(token); // decode does not verify the signature

05console.log(header, payload); // Outputs the decoded header and payload

Saída:

{ alg: 'HS256', typ: 'JWT' } { userId: 123 }

Erros

Uma chamada que falha lança, ou rejeita com, um erro cujo name é um dos sete abaixo. As declarações de tipo listam essas classes de erro como exports, mas o pacote não as exporta em tempo de execução: um arquivo que importa uma delas para no carregamento. Diferencie os erros por err.name, como faz o exemplo de verify. Para o erro de carregamento, consulte Solucionar problemas da Azion Lib.

Nas mensagens abaixo, <token> representa o token que a chamada recebeu.

Nome	Mensagem	Causa	O que fazer
`JwtAlgorithmNotImplemented`	`none is not an implemented algorithm`	O valor de `alg` não é um dos algoritmos que o pacote implementa.	Passe um valor de Chaves e algoritmos.
`JwtTokenInvalid`	`invalid JWT token: abc`	A string passada para `decode` ou `verify` não é um JWT.	Passe um token completo, como `sign` o retorna.
`JwtTokenNotBefore`	`token (<token>) is being used before it's valid`	O claim `nbf` está no futuro.	Verifique o token depois do horário em `nbf`.
`JwtTokenExpired`	`token (<token>) expired`	O claim `exp` está no passado.	Assine um token novo com um `exp` posterior.
`JwtTokenIssuedAt`	`Incorrect "iat" claim must be a older than "<current-time>" (iat: "<iat>")`	O claim `iat` é posterior ao horário atual.	Assine o token com um `iat` que não esteja no futuro.
`JwtHeaderInvalid`	`jwt header is invalid: {"alg":"HS256","typ":"XYZ"}`	O cabeçalho do token não é válido, como um `typ` diferente de `JWT`.	Assine o token com `sign`, que escreve `typ: 'JWT'`.
`JwtTokenSignatureMismatched`	`token(<token>) signature mismatched`	A chave não corresponde à chave que assinou o token.	Verifique com o mesmo segredo, ou com a chave pública do par que assinou o token.

Tipos

O pacote exporta um tipo, JWTPayload. Importe-o com import type. Os outros três tipos abaixo são declarados pelo pacote, mas não são exportados, então você não pode importá-los.

JWTPayload

Os claims de um token. Os horários são timestamps Unix, em segundos.

TypeScript

01type JWTPayload = {

02 [key: string]: unknown;

03 exp?: number;

04 nbf?: number;

05 iat?: number;

06};

Propriedade	Tipo	Obrigatório	Descrição
`[key: string]`	`unknown`	Não	Um claim personalizado, como `userId`.
`exp`	`number`	Não	O horário de expiração do token. Depois dele, verify rejeita com `JwtTokenExpired`.
`nbf`	`number`	Não	O horário antes do qual o token não é válido. Antes dele, `verify` rejeita com `JwtTokenNotBefore`.
`iat`	`number`	Não	O horário em que o token foi emitido. Um valor no futuro faz `verify` rejeitar com `JwtTokenIssuedAt`.

TokenHeader

O cabeçalho que decode retorna.

TypeScript

01interface TokenHeader {

02 alg: SignatureAlgorithm;

03 typ?: 'JWT';

04}

Propriedade	Tipo	Obrigatório	Descrição
`alg`	`SignatureAlgorithm`	Sim	O algoritmo que assinou o token.
`typ`	`'JWT'`	Não	O tipo do token.

SignatureAlgorithm

Os nomes de algoritmo que sign e verify recebem em alg. Para os 13 valores, consulte Chaves e algoritmos.

type SignatureAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512' | 'ES256' | 'ES384' | 'ES512' | 'EdDSA';

SignatureKey

A chave que sign e verify recebem.

type SignatureKey = string | JsonWebKey | CryptoKey;

Recursos relacionados

Azion Lib

As bibliotecas que a Azion Lib oferece e o pacote que contém cada uma.

Como a Azion Lib funciona

Quais módulos chamam uma API, quais lançam erros e onde cada um roda.

Solucionar problemas da Azion Lib

Correções para os erros de carregamento e de execução que os pacotes da Azion Lib retornam.

SubtleCrypto

Os métodos de crypto.subtle que geram e importam chaves.