gwt

Types

Algorithm

Available JSON Web Algorithms used for encoding and decdoing signatures in from_signed_string and to_signed_string.

If JWT calls for a different algorithm than the ones listed here from_signed_string will fail with the JwtDecodeError UnsupportedSigningAlgorithm.

pub type Algorithm {
  HS256
  HS384
  HS512
}

Constructors

```
HS256
```
```
HS384
```
```
HS512
```

Jwt

opaque </>

A decoded JWT that can be read. The phantom type status indicated if it’s signature was verified or not.

pub opaque type Jwt(status)

JwtBuilder

opaque </>

The intermediate representation of a JWT before being encoded to a String.

pub opaque type JwtBuilder

JwtDecodeError

</>

Errors that can occur when attempting to decode a JWT from a String or read from a successfully decoded JWT string.

pub type JwtDecodeError {
  MissingHeader
  MissingPayload
  MissingSignature
  InvalidHeader
  InvalidPayload
  InvalidSignature
  InvalidExpiration
  TokenExpired
  TokenNotValidYet
  InvalidNotBefore
  NoAlg
  InvalidAlg
  UnsupportedSigningAlgorithm
  MissingClaim
  InvalidClaim(List(DecodeError))
}

Constructors

```
MissingHeader
```
```
MissingPayload
```
```
MissingSignature
```
```
InvalidHeader
```
```
InvalidPayload
```
```
InvalidSignature
```
```
InvalidExpiration
```
```
TokenExpired
```
```
TokenNotValidYet
```
```
InvalidNotBefore
```
```
NoAlg
```
```
InvalidAlg
```
```
UnsupportedSigningAlgorithm
```
```
MissingClaim
```
```
InvalidClaim(List(DecodeError))
```

Unverified

</>

A phantom type representing an unverified Jwt.

pub type Unverified

Verified

</>

A phantom type representing a Jwt successfully decoded from a signed string.

pub type Verified

Functions

from_signed_string

</>

pub fn from_signed_string(
  jwt_string: String,
  secret: String,
) -> Result(Jwt(Verified), JwtDecodeError)

Decode a signed JWT string into a verified Jwt.

Returns Ok(JwtBuilder) if it is a valid JWT and the JWT’s signature is successfully verified, and Error(JwtDecodeError) otherwise.

At the moment this library only supports HS256, HS384, and HS512 hashing algorithms. if a JWT’s alg claim calls for any other this function will return Error(UnsupportedSigningAlgorithm).

import gwt.{type Jwt, type Verified, type JwtDecodeError}

fn example(jwt_string: String) -> Result(Jwt(Verified), JwtDecodeError) {
  gwt.from_signed_string(jwt_string, "some secret")
}

from_string

</>

pub fn from_string(
  jwt_string: String,
) -> Result(Jwt(Unverified), JwtDecodeError)

Decode a JWT string into an unverified Jwt.

Returns Ok(JwtBuilder) if it is a valid JWT, and Error(JwtDecodeError) otherwise.

import gwt.{type Jwt, type Unverified, type JwtDecodeError}

fn example(jwt_string: String) -> Result(JwtBuilder, JwtDecodeError) {
  gwt.from_string(jwt_string)
}

get_audience

</>

pub fn get_audience(
  from jwt: Jwt(a),
) -> Result(String, JwtDecodeError)

Retrieve the aud from the JWT’s payload.

Returns Error(Nil) if the sub is not present or if it is invalid.

If you know the aud claim is not of type String you can use get_payload_claim to retrieve and decode it manually.

import gwt

fn example()  {
  let jwt_with_aud = 
    gwt.new()
    |> jwt.set_audience("gleam")

  let assert Ok(audience) = gwt.get_audience(jwt_with_aud)

  let jwt_without_aud = gwt.new()

  let assert Error(MissingClaim) = gwt.get_audience(jwt_without_aud)
}

get_expiration

</>

pub fn get_expiration(
  from jwt: Jwt(a),
) -> Result(Int, JwtDecodeError)

Retrieve the exp from the JWT’s payload.

Returns Error(Nil) if the exp is not present or if it is invalid.

If you know the exp claim is not of type String you can use get_payload_claim to retrieve and decode it manually.

import gwt

fn example()  {
  let jwt_with_exp = 
    gwt.new()
    |> jwt.set_not_before("gleam")

  let assert Ok(expiration) = gwt.get_not_before(jwt_with_exp)

  let jwt_without_exp = gwt.new()

  let assert Error(MissingClaim) = gwt.get_not_before(jwt_without_exp)
}

get_header_claim

</>

pub fn get_header_claim(
  from jwt: Jwt(a),
  claim claim: String,
  decoder decoder: fn(Dynamic) -> Result(b, List(DecodeError)),
) -> Result(b, Nil)

Retrieve and decode a claim from a JWT’s header.

Returns Error if the claim is not present or if it is invalid based on the passed in decoder.

import gwt
import gleam/json
import gleam/dynamic

fn example() {
  let jwt_with_custom_claim =
    gwt.new()
    |> gwt.set_header_claim("gleam", json.string("lucy"))

  let assert Ok("lucy") =
    gwt.get_header_claim(jwt_with_custom_claim, "gleam", dynamic.string)

  let assert Error(MissingClaim) =
    gwt.get_header_claim(jwt_with_custom_claim, "gleam", dynamic.int)
}

get_issued_at

</>

pub fn get_issued_at(
  from jwt: Jwt(a),
) -> Result(Int, JwtDecodeError)

Retrieve the iat from the JWT’s payload.

Returns Error(Nil) if the iat is not present or if it is invalid.

If you know the iat claim is not of type String you can use get_payload_claim to retrieve and decode it manually.

import gwt

fn example()  {
  let jwt_with_iat = 
    gwt.new()
    |> jwt.set_issued_at("gleam")

  let assert Ok(issued_at) = gwt.get_issued_at(jwt_with_iat)

  let jwt_without_iat = gwt.new()

  let assert Error(MissingClaim) = gwt.get_issued_at(jwt_without_iat)
}

get_issuer

</>

pub fn get_issuer(
  from jwt: Jwt(a),
) -> Result(String, JwtDecodeError)

Retrieve the iss from the JWT’s payload.

Returns Error(Nil) if the iss is not present or if it is invalid.

If you know the iss claim is not of type String you can use get_payload_claim to retrieve and decode it manually.

import gwt

fn example()  {
  let jwt_with_iss = 
    gwt.new()
    |> jwt.set_issuer("gleam")

  let assert Ok(issuer) = gwt.get_issuer(jwt_with_iss)

  let jwt_without_iss = gwt.new()

  let assert Error(MissingClaim) = gwt.get_issuer(jwt_without_iss)
}

get_jwt_id

</>

pub fn get_jwt_id(
  from jwt: Jwt(a),
) -> Result(String, JwtDecodeError)

Retrieve the jti from the JWT’s payload.

Returns Error(Nil) if the jti is not present or if it is invalid.

If you know the jti claim is not of type String you can use get_payload_claim to retrieve and decode it manually.

import gwt

fn example()  {
  let jwt_with_jti = 
    gwt.new()
    |> jwt.set_jwt_id("gleam")

  let assert Ok(jwt_id) = gwt.get_jwt_id(jwt_with_jti)

  let jwt_without_jti = gwt.new()

  let assert Error(MissingClaim) = gwt.get_jwt_id(jwt_without_jti)
}

get_not_before

</>

pub fn get_not_before(
  from jwt: Jwt(a),
) -> Result(Int, JwtDecodeError)

Retrieve the nbf from the JWT’s payload.

Returns Error(Nil) if the nbf is not present or if it is invalid.

If you know the nbf claim is not of type String you can use get_payload_claim to retrieve and decode it manually.

import gwt

fn example()  {
  let jwt_with_sub = 
    gwt.new()
    |> jwt.set_not_before("gleam")

  let assert Ok(not_before) = gwt.get_not_before(jwt_with_nbf)

  let jwt_without_nbf = gwt.new()

  let assert Error(MissingClaim) = gwt.get_not_before(jwt_without_nbf)
}

get_payload_claim

</>

pub fn get_payload_claim(
  from jwt: Jwt(a),
  claim claim: String,
  decoder decoder: fn(Dynamic) -> Result(b, List(DecodeError)),
) -> Result(b, JwtDecodeError)

Retrieve and decode a claim from a JWT’s payload.

Returns Error if the claim is not present or if it is invalid based on the passed in decoder.

import gwt
import gleam/json
import gleam/dynamic

fn example() {
  let jwt_with_custom_claim =
    gwt.new()
    |> gwt.set_payload_claim("gleam", json.string("lucy"))

  let assert Ok("lucy") =
    gwt.get_payload_claim(jwt_with_custom_claim, "gleam", dynamic.string)

  let assert Error(MissingClaim) =
    gwt.get_payload_claim(jwt_with_custom_claim, "gleam", dynamic.int)
}

get_subject

</>

pub fn get_subject(
  from jwt: Jwt(a),
) -> Result(String, JwtDecodeError)

Retrieve the sub from the JWT’s payload.

Returns Error(Nil) if the sub is not present or if it is invalid.

If you know the sub claim is not of type String you can use get_payload_claim to retrieve and decode it manually.

import gwt

fn example()  {
  let jwt_with_sub = 
    gwt.new()
    |> jwt.set_subject("gleam")

  let assert Ok(subject) = gwt.get_issuer(jwt_with_sub)

  let jwt_without_sub = gwt.new()

  let assert Error(MissingClaim) = gwt.get_subject(jwt_without_sub)
}

new

</>

pub fn new() -> JwtBuilder

Creates a JwtBuilder with an empty payload and a header that only contains the cliams "typ": "JWT", and "alg": "none".

import gwt.{type Jwt, type Unverified}

fn example() -> JwtBuilder {
  gwt.new()
}

set_audience

</>

pub fn set_audience(
  jwt: JwtBuilder,
  to aud: String,
) -> JwtBuilder

Set the aud claim of a payload.

import gwt

fn example() {
  gwt.new()
  |> gwt.set_audience("gleam")
}

set_expiration

</>

pub fn set_expiration(jwt: JwtBuilder, to exp: Int) -> JwtBuilder

Set the exp claim of a payload.

import gwt
import birl

fn example() {
  let five_minutes = birl.to_unix(birl.now()) + 300

  gwt.new()
  |> gwt.set_expiration(five_minutes)
}

set_header_claim

</>

pub fn set_header_claim(
  jwt: JwtBuilder,
  set claim: String,
  to value: Json,
) -> JwtBuilder

Set a custom header claim to a given JSON value.

import gleam/json
import gwt

fn example() {
  gwt.new()
  |> gwt.set_header_claim("gleam", json.string("lucy"))
}

set_issued_at

</>

pub fn set_issued_at(jwt: JwtBuilder, to iat: Int) -> JwtBuilder

Set the nbf claim of a payload.

import gwt
import birl

fn example() {
  gwt.new()
  |> gwt.set_not_before(birl.to_unix(birl.now()))
}

set_issuer

</>

pub fn set_issuer(jwt: JwtBuilder, to iss: String) -> JwtBuilder

Set the iss claim of a payload.

import gwt

fn example() {
  gwt.new()
  |> gwt.set_issuer("gleam")
}

set_jwt_id

</>

pub fn set_jwt_id(jwt: JwtBuilder, to jti: String) -> JwtBuilder

Set the jti claim of a payload.

import gwt
import birl

fn example() {
  gwt.new()
  |> gwt.set_jwt_id("gleam")
}

set_not_before

</>

pub fn set_not_before(jwt: JwtBuilder, to nbf: Int) -> JwtBuilder

Set the nbf claim of a payload.

import gwt
import birl

fn example() {
  let five_minutes = birl.to_unix(birl.now()) + 300

  gwt.new()
  |> gwt.set_not_before(five_minutes)
}

set_payload_claim

</>

pub fn set_payload_claim(
  jwt: JwtBuilder,
  set claim: String,
  to value: Json,
) -> JwtBuilder

Set a custom payload claim to a given JSON value.

import gleam/json
import gwt

fn example() {
  gwt.new()
  |> gwt.set_payload_claim("gleam", json.string("lucy"))
}

set_subject

</>

pub fn set_subject(jwt: JwtBuilder, to sub: String) -> JwtBuilder

Set the sub claim of a payload.

import gwt

fn example() {
  gwt.new()
  |> gwt.set_subject("gleam")
}

to_signed_string

</>

pub fn to_signed_string(
  jwt: JwtBuilder,
  alg: Algorithm,
  secret: String,
) -> String

Encode a Jwt to a signed String using the given Algorithm and secret.

import gwt

fn example() {
  gwt.new()
  |> gwt.set_issuer("gleam")
  |> gwt.to_signed_string(gwt.HS256, "lucy")
}

to_string

</>

pub fn to_string(jwt: JwtBuilder) -> String

Encode a Jwt to a String without a signature

import gwt

fn example() {
  gwt.new()
  |> gwt.set_issuer("gleam")
  |> gwt.to_string()
}