# Biblioteca `JWT` da Azion

import DocButton from '~/components/webkit/DocButton.vue';

A biblioteca **JWT** da Azion fornece funções utilitárias para assinar, verificar e decodificar **JSON Web Tokens (JWTs)**. Essa biblioteca garante facilidade de uso e segurança ao lidar com JWTs em aplicações web.

<DocButton href="/pt-br/documentacao/produtos/azion-lib/visao-geral/" label="Saiba mais sobre as Azion Libraries" kind="secondary" size="medium" />

---

## Uso

### `sign`

Assina um payload JWT com o algoritmo e chave privada especificados.

Exemplo:

```typescript
import { sign } from 'azion/jwt';
import type { JWTPayload } from 'azion/jwt';

const privateKey: string = 'your-private-key';
const payload: JWTPayload = { userId: 123, exp: Math.floor(Date.now() / 1000) + 3600 }; // Expiração em 1 hora
sign(payload, privateKey).then((token: string) => console.log(token)); // Exibe o JWT assinado
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `payload` | `JWTPayload` | O payload a ser assinado. |
| `privateKey` | `SignatureKey` | A chave privada usada para assinar. |
| `alg` | `SignatureAlgorithm` | O algoritmo a ser usado para assinar. Padrão: `'HS256'`. |

**Retorno**:

| Tipo de retorno | Descrição |
|-----------------|-------------|
| `Promise<string>` | O JWT assinado. |

### `verify`

Verifica um JWT usando a chave pública e algoritmo especificados.

Exemplo:

```typescript
import { verify } from 'azion/jwt';
import type { JWTPayload } from 'azion/jwt';

const publicKey: string = 'your-public-key';
const token: string = 'your-jwt-token';
verify(token, publicKey)
  .then((payload: JWTPayload) => console.log(payload))
  .catch((err) => console.error(err)); // Exibe o payload se a verificação for bem-sucedida
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `token` | `string` | O JWT a ser verificado. |
| `publicKey` | `SignatureKey` | A chave pública usada para verificação. |
| `alg` | `SignatureAlgorithm` (opcional) | O algoritmo a ser usado para a verificação. Padrão: `'HS256'`. |

**Retorno**:

| Tipo de retorno | Descrição |
|-----------------|-------------|
| `Promise<JWTPayload>` | O payload decodificado se o token for válido. |

### `decode`

Decodifica um JWT sem verificar a assinatura.

```typescript
import { decode } from 'azion/jwt';
import type { JWTPayload, TokenHeader } from 'azion/jwt';

const token: string = 'your-jwt-token';
const { header, payload }: { header: TokenHeader; payload: JWTPayload } = decode(token);
console.log(header, payload); // Exibe o cabeçalho e payload decodificados
```
**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `token` | `string` | O JWT a ser decodificado. |

**Retorno**:

| Tipo de retorno | Descrição |
|-----------------|-------------|
| `{ header: TokenHeader; payload: JWTPayload }` | O cabeçalho e payload decodificados. |

---

## Tipos

Os seguintes tipos definem a estrutura dos dados usados na biblioteca **JWT**.

### `JWTPayload`

Define a estrutura do payload do JWT.

```typescript
type JWTPayload = {
  [key: string]: unknown;
  exp?: number;
  nbf?: number;
  iat?: number;
};
```
**Parâmetros**:

| Parâmetro | Tipo     | Descrição                                      |
|-----------|----------|--------------------------------------------------|
| `key`     | `string` | Um par chave-valor personalizado no payload.   |
| `exp`     | `number` | O tempo de expiração do token, em segundos.    |
| `nbf`     | `number` | O tempo antes do qual o token não é válido.   |
| `iat`     | `number` | O tempo em que o token foi emitido, em segundos. |

### `TokenHeader`

Define a estrutura do cabeçalho do JWT.

```typescript
interface TokenHeader {
  alg: SignatureAlgorithm;
  typ?: 'JWT';
}
```

**Parâmetros**:

| Parâmetro | Tipo               | Descrição                                   |
|-----------|--------------------|---------------------------------------------|
| `alg`     | `SignatureAlgorithm` | O algoritmo usado para assinar o JWT.      |
| `typ`     | `string` (opcional) | O tipo do token, tipicamente 'JWT'.        |

---

## Erros

Estes são os tipos de erros que podem ser retornados pelos métodos da biblioteca.

### `JwtAlgorithmNotImplemented`

Lançado quando um algoritmo não está implementado.

### `JwtTokenInvalid`

Lançado quando um JWT é inválido.

### `JwtTokenNotBefore`

Lançado quando um JWT é usado antes do seu claim `nbf`.

### `JwtTokenExpired`

Lançado quando um JWT expirou.

### `JwtTokenIssuedAt`

Lançado quando um claim `iat` de um JWT está no futuro.

### `JwtHeaderInvalid`

Lançado quando um cabeçalho de JWT é inválido.

### `JwtTokenSignatureMismatched`

Lançado quando a assinatura de um JWT não corresponde.