kit-jwt

JSON Web Token (JWT) encoding and decoding for Kit

[TOC]

Files

Dependencies

• Kit package dependency: crypto
• Kit standard module: Encoding.Base64
• Native library: OpenSSL libcrypto for RS256, RS384, and RS512 helpers
• Capability required: ffi

The package is declared as ffi-zig because RSA signing and verification use zig/jwt_rsa.zig. HS256 uses crypto.hmac-sha256.

Installation

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

Usage

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 "Failed to create token:"
      println e
    | Ok token ->
      println "JWT:"
      println token

      if JWT.verify? token secret then
        println "Token is valid"
      else
        println "Token is invalid"

      match JWT.decode token secret
        | Ok decoded ->
          println "Header:"
          println decoded.header
          println "Payload:"
          println decoded.payload
        | Err e ->
          println "Decode failed:"
          println e

main

Supported signing and verification helpers:

Unsafe inspection helpers are also available for debugging tokens without verifying signatures:

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

Do not use unsafe helpers for authorization decisions.

Development

Running Examples

Run the basic example with the interpreter:

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

Compile the example to a native binary:

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

Running Tests

Run the active test suite:

kit test --allow=ffi

Run the active test suite with coverage:

kit test --coverage --allow=ffi

Run the optional RSA test files directly:

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

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Check formatting for Kit source and example files
2. Type check source and examples
3. Run active tests with coverage

Running Parity

Run interpreter/compiler parity checks for examples:

kit parity --failures-only

Parity checks that examples run through the interpreter, compile successfully, execute successfully, and produce matching output.

Generating Documentation

Generate API documentation from doc comments:

kit doc src/jwt.kit

Note: Kit sources with doc comments (##) generate HTML documentation.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/jwt/, making it available for import as Kit.Jwt in other projects.

Security Notes

• Use strong, random HS256 secrets. A minimum of 256 bits is recommended.
• Never commit private keys or production JWT secrets.
• Validate application claims such as exp, nbf, iat, iss, and aud after decoding.
• Prefer short-lived tokens and rotate keys according to your application's threat model.
• Use HTTPS whenever transmitting JWTs over a network.

License

This package is released under the MIT License - see LICENSE for details.