Jots

Jots is a library for working with JSON Web Tokens (JWTs) in Scala, Scala.js and Scala Native.

Features cross-platform cryptography for Scala, Scala.js (Node.js) and Scala Native (OpenSSL).
Supports signing and verification for standard ECDSA, EdDSA, HMAC and RSA algorithms.
Provides testing support with ScalaCheck generators and String interpolators for secrets.
Separates token parsing and verification, so tokens can be inspected before verification.
Handles token signature verification using keys from a JSON Web Key Set (JWK Set).
Based on the cats-effect, circe-jawn, literally and scodec-bits libraries.

Documentation is kept up-to-date, currently documenting v0.1.1 on Scala 3.3.

Getting Started

To get started with sbt, add the following line to your build.sbt file.

libraryDependencies += "se.vlovgr" %% "jots" % "0.1.1"

Published for Scala 2.13 and 3.3, Scala.js 1.22 and Scala Native 0.5.

For changes between versions, please refer to the release notes.

For Scala.js or Scala Native, replace the %% with %%% above.

Signing and verification is covered in the introduction.

Runtime Versions

The library relies on each platform's native cryptography. The minimum required runtime version depends on the platform and algorithms being used. Prefer the latest runtime version available, as it usually has the best security posture. Following is some general guidance on minimum recommended versions.

For Scala on the JVM, use Java 17 (LTS) or a later version.
For Scala.js on Node.js, use Node.js 22 (LTS) or a later version.
For Scala Native using OpenSSL, use OpenSSL 3.x or a later version.

Supported Algorithms

Refer to the table below for a list of supported signing algorithms.

Algorithm	Algorithm Description
`Ed25519`	EdDSA using the Ed25519 curve
`Ed448`	EdDSA using the Ed448 curve
`ES256`	ECDSA using P-256 and SHA-256
`ES384`	ECDSA using P-384 and SHA-384
`ES512`	ECDSA using P-521 and SHA-512
`HS256`	HMAC using SHA-256
`HS384`	HMAC using SHA-384
`HS512`	HMAC using SHA-512
`PS256`	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
`PS384`	RSASSA-PSS using SHA-384 and MGF1 with SHA-384
`PS512`	RSASSA-PSS using SHA-512 and MGF1 with SHA-512
`RS256`	RSASSA-PKCS-v1_5 using SHA-256
`RS384`	RSASSA-PKCS-v1_5 using SHA-384
`RS512`	RSASSA-PKCS-v1_5 using SHA-512

Dependencies

Refer to the table below for dependencies and version support across modules.

Module	Dependencies	Scala
`jots`	`jots-crypto` and circe-jawn 0.14.16	Scala 2.13 and 3.3
`jots-crypto`	cats-effect-kernel 3.7.0, literally 1.2.0, scodec-bits 1.2.5	Scala 2.13 and 3.3
`jots-testing`	`jots` and cats-effect 3.7.0, scalacheck 1.19.0	Scala 2.13 and 3.3

For Scala.js and Scala Native version support, refer to the following table.

Module	Scala.js	Scala Native
`jots`	Scala.js 1.22 (Scala 2.13 and 3.3)	Scala Native 0.5 (Scala 2.13 and 3.3)
`jots-crypto`	Scala.js 1.22 (Scala 2.13 and 3.3)	Scala Native 0.5 (Scala 2.13 and 3.3)
`jots-testing`	Scala.js 1.22 (Scala 2.13 and 3.3)	Scala Native 0.5 (Scala 2.13 and 3.3)

Compatibility

Backwards binary compatibility for the library is guaranteed between patch versions.

Release version 0.a.b is backwards binary compatible with 0.a.c for any b > c.

The compatibility guarantee is according to the Early SemVer version scheme.

Signatures

Stable release artifacts are signed with the 0DF8 8F31 EB37 24D8 key.

Snapshots

To use the latest snapshot release, add the following lines to your build.sbt file.

resolvers += Resolver.sonatypeCentralSnapshots

libraryDependencies += "se.vlovgr" %% "jots" % "0.1.1-2-3404a7e-SNAPSHOT"

License

The library is distributed under the Apache License, Version 2.0.