kit-jwt

Codificação e decodificação de JSON Web Token (JWT) para Kit

[TOC]

Arquivos

Dependências

• Dependência de pacote Kit: crypto
• Módulo padrão Kit: Encoding.Base64
• Biblioteca nativa: OpenSSL libcrypto para auxiliares RS256, RS384 e RS512
• Capacidade necessária: ffi

O pacote é declarado como ffi-zig porque a assinatura e verificação RSA usam zig/jwt_rsa.zig. HS256 usa crypto.hmac-sha256.

Instalação

kit add gitlab.com/kit-lang/packages/kit-jwt.git

Uso

import Kit.Jwt as JWT

main = fn =>
  secret = "my-super-secret-key-at-least-32-chars"
  claims = "{\"sub\":\"user123\",\"name\":\"John Doe\",\"admin\":true,\"iat\":1700000000}"

  match JWT.encode claims secret
    | Err e ->
      println "Falha ao criar token:"
      println e
    | Ok token ->
      println "JWT:"
      println token

      if JWT.verify? token secret then
        println "Token é válido"
      else
        println "Token é inválido"

      match JWT.decode token secret
        | Ok decoded ->
          println "Cabeçalho:"
          println decoded.header
          println "Payload:"
          println decoded.payload
        | Err e ->
          println "Falha na decodificação:"
          println e

main

Funções auxiliares de assinatura e verificação suportadas:

Funções auxiliares de inspeção insegura também estão disponíveis para depuração de tokens sem verificar assinaturas:

• decode-unsafe
• get-claims-unsafe
• get-header-unsafe

Não use funções auxiliares inseguras para decisões de autorização.

Desenvolvimento

Executando Exemplos

Execute o exemplo básico com o interpretador:

kit run examples/basic.kit --allow=ffi

Compile o exemplo para um binário nativo:

kit build examples/basic.kit --allow=ffi && ./basic

Executando Testes

Execute a suíte de testes ativa:

kit test --allow=ffi

Execute a suíte de testes ativa com cobertura:

kit test --coverage --allow=ffi

Execute os arquivos de teste RSA opcionais diretamente:

kit test tests/rs256.kit.disabled --allow=ffi
kit test tests/rs384.kit.disabled --allow=ffi
kit test tests/rs512.kit.disabled --allow=ffi

Executando kit dev

Execute o fluxo de trabalho de desenvolvimento padrão (formatar, verificar, testar):

kit dev

Isso irá:

1. Verificar formatação dos arquivos fonte e exemplos Kit
2. Verificar tipos dos fontes e exemplos
3. Executar testes ativos com cobertura

Executando Verificação de Paridade

Execute verificações de paridade interpretador/compilador para exemplos:

kit parity --failures-only

As verificações de paridade garantem que os exemplos executam pelo interpretador, compilam com sucesso, executam com sucesso e produzem saída correspondente.

Gerando Documentação

Gere documentação da API a partir de comentários de documentação:

kit doc src/jwt.kit

Nota: Fontes Kit com comentários de documentação (##) geram documentação HTML.

Limpando Artefatos de Build

Remova arquivos gerados, caches e artefatos de build:

kit task clean

Nota: Definido em kit.toml.

Instalação Local

Para instalar este pacote localmente para desenvolvimento:

kit install

Isso instala o pacote em ~/.kit/packages/@kit/jwt/, tornando-o disponível para importação como Kit.Jwt em outros projetos.

Notas de Segurança

• Use segredos HS256 fortes e aleatórios. Recomenda-se no mínimo 256 bits.
• Nunca envie chaves privadas ou segredos JWT de produção.
• Valide claims da aplicação como exp, nbf, iat, iss e aud após a decodificação.
• Prefira tokens de curta duração e rotacione chaves de acordo com o modelo de ameaça da sua aplicação.
• Use HTTPS sempre que transmitir JWTs por uma rede.

Licença

Este pacote é lançado sob a Licença MIT - consulte LICENSE para detalhes.