gose

A Gleam implementation of JOSE (JSON Object Signing and Encryption) standards:

• JWS (RFC 7515) - JSON Web Signature
• JWE (RFC 7516) - JSON Web Encryption
• JWK (RFC 7517) - JSON Web Key
• JWA (RFC 7518) - JSON Web Algorithms
• JWT (RFC 7519) - JSON Web Token

Project Goals

• Type-Safe by Design - types enforce correct API usage at compile time. Unsigned JWS can’t be serialized, unverified JWT claims can’t be trusted.
• Algorithm Pinning - JWT/JWS/JWE require explicit algorithm declaration, preventing algorithm confusion attacks common in other JOSE libraries. It trades off verbosity for security.
• Invalid States Are Unconstructable - Keys and tokens are validated at construction time. If you have a Jwk, it’s valid.

Installation

gleam add gose

Platform support

• Erlang/OTP 27+
• Node.js 22+

Browser JavaScript is not supported.

Supported Algorithms

All algorithms below apply to both raw JWS/JWE operations and JWT signing and encryption.

JWS Signing

JWE Key Management

JWE Content Encryption

Quick Start

JWT - Creating and Verifying Tokens

import gleam/dynamic/decode
import gleam/option.{None}
import gleam/time/duration
import gleam/time/timestamp
import gose/jwa
import gose/jwk
import gose/jwt

pub fn main() {
  // Generate a symmetric key for HS256
  let key = jwk.generate_hmac_key(jwa.HmacSha256)
  let now = timestamp.system_time()

  // Create claims
  let claims =
    jwt.claims()
    |> jwt.with_subject("user123")
    |> jwt.with_issuer("my-app")
    |> jwt.with_expiration(timestamp.add(now, duration.hours(1)))

  // Sign the JWT
  let assert Ok(signed) = jwt.sign(jwa.JwsHmac(jwa.HmacSha256), claims, key)

  // Serialize to compact format
  let token = jwt.serialize(signed)

  // Verify and validate
  let assert Ok(verifier) =
    jwt.verifier(jwa.JwsHmac(jwa.HmacSha256), [key], jwt.default_validation())
  let assert Ok(verified) = jwt.verify_and_validate(verifier, token, now)

  // Decode verified claims
  let decoder = decode.field("sub", decode.string, decode.success)
  let assert Ok("user123") = jwt.decode(verified, decoder)
}

JWS - Signing Data

import gose/jwa
import gose/jwk
import gose/jws
import kryptos/eddsa

pub fn main() {
  // Generate an Ed25519 key
  let key = jwk.generate_eddsa(eddsa.Ed25519)
  let payload = <<"hello world":utf8>>

  // Create and sign
  let assert Ok(signed) =
    jws.new(jwa.JwsEddsa)
    |> jws.sign(key, payload)

  // Serialize to compact format
  let assert Ok(token) = jws.serialize_compact(signed)

  // Parse and verify using a Verifier
  let assert Ok(parsed) = jws.parse_compact(token)
  let assert Ok(verifier) = jws.verifier(jwa.JwsEddsa, [key])
  let assert Ok(True) = jws.verify(verifier, parsed)
}

JWE - Encrypting Data

import gose/jwa
import gose/jwe
import gose/jwk

pub fn main() {
  // Generate a 256-bit key for direct encryption with AES-256-GCM
  let key = jwk.generate_enc_key(jwa.AesGcm(jwa.Aes256))
  let plaintext = <<"sensitive data":utf8>>

  // Encrypt using direct key encryption
  let assert Ok(encrypted) =
    jwe.new_direct(jwa.AesGcm(jwa.Aes256))
    |> jwe.encrypt(key, plaintext)

  // Serialize to compact format
  let assert Ok(token) = jwe.serialize_compact(encrypted)

  // Parse and decrypt with algorithm pinning
  let assert Ok(parsed) = jwe.parse_compact(token)
  let assert Ok(decryptor) = jwe.key_decryptor(jwa.JweDirect, jwa.AesGcm(jwa.Aes256), [key])
  let assert Ok(decrypted) = jwe.decrypt(decryptor, parsed)
  // decrypted == <<"sensitive data":utf8>>
}

Error Handling

The library uses a two-tier error design:

GoseError — used by JOSE primitives (JWS, JWE, JWK):

JwtError — used by JWT and encrypted JWT modules:

Limitations

• X.509 certificate parameters not supported - JWKs containing X.509 certificate chain parameters (x5u, x5c, x5t, x5t#S256) are rejected with a parse error. Certificate-based key validation must be performed outside this library.

Documentation

Full API documentation is available at hexdocs.pm/gose.