Overview

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 signing with a JSON Web Key (JWK) and verification with a JWK Set.
Integrates with http4s for authentication and for JWK Set refreshing verification.
Based on the cats-effect, circe-jawn, literally and scodec-bits libraries.

Documentation is kept up-to-date, currently documenting v0.4.0 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.4.0"

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 (Java, Node.js and OpenSSL). 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 21 (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-PKCS1-v1_5 using SHA-256
`RS384`	RSASSA-PKCS1-v1_5 using SHA-384
`RS512`	RSASSA-PKCS1-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.17	Scala 2.13 and 3.3
`jots-crypto`	cats-effect-kernel 3.7.1, literally 1.2.0, scodec-bits 1.2.5	Scala 2.13 and 3.3
`jots-http4s`	`jots` and http4s 0.23.38	Scala 2.13 and 3.3
`jots-testing`	`jots` and cats-effect 3.7.1, scalacheck 1.20.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-http4s`	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)

Specifications

Refer to the table below for specifications relevant to the library.

Specification	Description
RFC 5280	Internet X.509 PKI Certificate and CRL Profile
RFC 5915	Elliptic Curve Private Key Structure (SEC 1)
RFC 5958	Asymmetric Key Packages (PKCS #8)
RFC 6750	OAuth 2.0 Bearer Token Usage
RFC 7468	Textual Encodings of PKIX, PKCS, and CMS Structures (PEM)
RFC 7515	JSON Web Signature (JWS)
RFC 7517	JSON Web Key (JWK)
RFC 7518	JSON Web Algorithms (JWA)
RFC 7519	JSON Web Token (JWT)
RFC 8017	RSA Cryptography Specifications (PKCS #1)
RFC 8037	CFRG ECDH and Signatures in JOSE
RFC 8725	JSON Web Token Best Current Practices
RFC 9864	Fully-Specified Algorithms for JOSE and COSE

The following IANA registries list the registered names used by the library.

JSON Object Signing and Encryption (JOSE) for algorithms, header parameters and keys.
JSON Web Token (JWT) for the standard registered claims normally used in JWTs.
Media Types for the media types for JWT, JSON Web Key (JWK) and JWK Set.
HTTP Authentication Schemes for the Bearer authentication scheme.

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.4.0-17-66958a8-SNAPSHOT"

Participation

Everyone is expected to follow the Typelevel Code of Conduct as described here.

License

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