allowing to override json and cryptography provider instance if needed

Author: faogustavo

docs/usage.md

@@ -767,6 +767,67 @@ val jwe = parser.parseEncrypted(token)
 
 ---
 
+## Customising the `Json` Instance
+
+By default, KJWT uses an internal `Json` configured with `ignoreUnknownKeys = true` and
+`explicitNulls = false`. This handles the most common use cases. If your application needs
+different serialization behaviour — for example, `encodeDefaults = true` or custom serializers
+registered via a `SerializersModule` — you can supply your own `Json` instance.
+
+### Builder and parser
+
+Pass a custom `Json` to `Jwt.builder()` or `Jwt.parser()`. The instance propagates automatically
+to every JSON operation performed by that builder or parser (claim serialization, payload and
+header encoding/decoding, etc.):
+
+```kotlin
+val customJson = Json {
+    ignoreUnknownKeys = true
+    explicitNulls = false
+    serializersModule = mySerializersModule
+}
+
+// builder — affects claim/payload/header serialization
+val jws = Jwt.builder(customJson)
+    .subject("user-123")
+    .payload(UserClaims(role = "admin"))
+    .signWith(signingKey)
+
+// parser — affects payload/header deserialization
+val parser = Jwt.parser(customJson)
+    .verifyWith(signingKey)
+    .build()
+```
+
+### Per-call overrides
+
+Methods that directly perform JSON serialization also accept an optional `jsonInstance` parameter,
+so you can override the instance for a single call without rebuilding the whole builder or parser:
+
+```kotlin
+// Deserialize the payload with a custom Json
+val claims: UserClaims = jws.getPayload<UserClaims>(jsonInstance = customJson)
+
+// Deserialize the header with a custom Json
+val header: MyHeader = jws.getHeader<MyHeader>(jsonInstance = customJson)
+
+// Read a custom claim with a custom Json
+val role: String = jws.payload.getClaim(String.serializer(), "role", jsonInstance = customJson)
+
+// Set a header parameter using a custom Json (JwtHeader.Builder)
+headerBuilder.extra("x-meta", MyMeta.serializer(), meta, jsonInstance = customJson)
+headerBuilder.takeFrom(MyHeader.serializer(), myHeader, jsonInstance = customJson)
+
+// Set a payload claim using a custom Json (JwtPayload.Builder)
+payloadBuilder.claim("meta", MyMeta.serializer(), meta, jsonInstance = customJson)
+payloadBuilder.takeFrom(UserClaims.serializer(), claims, jsonInstance = customJson)
+```
+
+All `jsonInstance` parameters default to the library's built-in `JwtJson`, so existing code
+requires no changes.
+
+---
+
 ## API Stability Annotations
 
 KJWT uses two opt-in annotations to communicate the stability of its API surface.

lib/build.gradle.kts

@@ -8,11 +8,11 @@ description = "Kotlin Multiplaftorm JWT"
 kotlin {
     sourceSets {
         commonMain.dependencies {
-            implementation(libs.kotlinx.coroutines.core)
-            implementation(libs.kotlinx.serialization.json)
-
             api(libs.cryptography.core)
-            implementation(libs.cryptography.bigint)
+            api(libs.cryptography.bigint)
+            api(libs.kotlinx.serialization.json)
+
+            implementation(libs.kotlinx.coroutines.core)
             implementation(libs.cryptography.serialization.asn1)
             implementation(libs.cryptography.serialization.asn1.modules)
         }

lib/src/commonMain/kotlin/co/touchlab/kjwt/Jwt.kt

@@ -1,7 +1,9 @@
 package co.touchlab.kjwt
 
 import co.touchlab.kjwt.builder.JwtBuilder
+import co.touchlab.kjwt.internal.JwtJson
 import co.touchlab.kjwt.parser.JwtParserBuilder
+import kotlinx.serialization.json.Json
 
 /**
  * Entry point for the KJWT library.
@@ -45,7 +47,27 @@ import co.touchlab.kjwt.parser.JwtParserBuilder
  * `cryptography-provider-optimal` to your app dependencies — it auto-registers on startup.
  */
 public object Jwt {
-    public fun builder(): JwtBuilder = JwtBuilder()
+    /**
+     * Creates a new [JwtBuilder] for constructing JWS or JWE tokens.
+     *
+     * @param jsonInstance the [Json] instance to use for all serialization within this builder;
+     *   defaults to the library's internal configuration (`ignoreUnknownKeys = true`,
+     *   `explicitNulls = false`)
+     * @return a new [JwtBuilder]
+     */
+    public fun builder(
+        jsonInstance: Json = JwtJson,
+    ): JwtBuilder = JwtBuilder(jsonInstance)
 
-    public fun parser(): JwtParserBuilder = JwtParserBuilder()
+    /**
+     * Creates a new [JwtParserBuilder] for parsing and validating JWS or JWE tokens.
+     *
+     * @param jsonInstance the [Json] instance to use for all deserialization within this parser;
+     *   defaults to the library's internal configuration (`ignoreUnknownKeys = true`,
+     *   `explicitNulls = false`)
+     * @return a new [JwtParserBuilder]
+     */
+    public fun parser(
+        jsonInstance: Json = JwtJson,
+    ): JwtParserBuilder = JwtParserBuilder(jsonInstance)
 }

lib/src/commonMain/kotlin/co/touchlab/kjwt/builder/JwtBuilder.kt

@@ -1,7 +1,6 @@
 package co.touchlab.kjwt.builder
 
 import co.touchlab.kjwt.cryptography.SimpleKey
-import co.touchlab.kjwt.internal.JwtJson
 import co.touchlab.kjwt.internal.encodeBase64Url
 import co.touchlab.kjwt.internal.encodeToBase64Url
 import co.touchlab.kjwt.model.JwtHeader
@@ -16,6 +15,7 @@ import co.touchlab.kjwt.model.registry.SigningKey
 import co.touchlab.kjwt.model.registry.SigningKey.Identifier
 import dev.whyoleg.cryptography.materials.key.Key
 import kotlinx.serialization.SerializationStrategy
+import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonElement
 import kotlin.time.Duration
 import kotlin.time.Instant
@@ -42,7 +42,9 @@ import kotlin.uuid.ExperimentalUuidApi
  *     .encryptWith(encKey, EncryptionContentAlgorithm.A256GCM)
  * ```
  */
-public class JwtBuilder {
+public class JwtBuilder(
+    internal val jsonInstance: Json,
+) {
     @PublishedApi
     internal val payloadBuilder: JwtPayload.Builder = JwtPayload.Builder()
 
@@ -159,7 +161,7 @@ public class JwtBuilder {
         name: String,
         serializer: SerializationStrategy<T>,
         value: T?,
-    ): JwtBuilder = apply { payloadBuilder.claim(name, serializer, value) }
+    ): JwtBuilder = apply { payloadBuilder.claim(name, serializer, value, jsonInstance) }
 
     /**
      * Sets a typed claim, inferring the serializer from the reified type [T].
@@ -194,7 +196,7 @@ public class JwtBuilder {
     public fun <T> payload(
         serializer: SerializationStrategy<T>,
         value: T,
-    ): JwtBuilder = apply { payloadBuilder.takeFrom(serializer, value) }
+    ): JwtBuilder = apply { payloadBuilder.takeFrom(serializer, value, jsonInstance) }
 
     /**
      * Merges all fields from [value] into the payload, inferring the serializer from the reified
@@ -249,7 +251,7 @@ public class JwtBuilder {
         name: String,
         serializer: SerializationStrategy<T>,
         value: T?,
-    ): JwtBuilder = apply { headerBuilder.extra(name, serializer, value) }
+    ): JwtBuilder = apply { headerBuilder.extra(name, serializer, value, jsonInstance) }
 
     /**
      * Sets a typed extra header parameter, inferring the serializer from the reified type [T].
@@ -284,7 +286,7 @@ public class JwtBuilder {
     public fun <T> header(
         serializer: SerializationStrategy<T>,
         value: T,
-    ): JwtBuilder = apply { headerBuilder.takeFrom(serializer, value) }
+    ): JwtBuilder = apply { headerBuilder.takeFrom(serializer, value, jsonInstance) }
 
     /**
      * Merges all fields from [value] into the JOSE header, inferring the serializer from the
@@ -492,9 +494,9 @@ public class JwtBuilder {
         val header = headerBuilder.build(key.identifier.algorithm, contentAlgorithm, keyId)
         val payload = payloadBuilder.build()
 
-        val headerB64 = JwtJson.encodeToBase64Url(header)
+        val headerB64 = jsonInstance.encodeToBase64Url(header)
         val aad = headerB64.encodeToByteArray()
-        val plaintext = JwtJson.encodeToString(payload).encodeToByteArray()
+        val plaintext = jsonInstance.encodeToString(payload).encodeToByteArray()
 
         val result = key.encrypt(contentAlgorithm, plaintext, aad)
 

lib/src/commonMain/kotlin/co/touchlab/kjwt/ext/JwkExt.kt

@@ -27,17 +27,21 @@ import dev.whyoleg.cryptography.serialization.asn1.modules.RsaKeyAlgorithmIdenti
 import dev.whyoleg.cryptography.serialization.asn1.modules.RsaPrivateKey
 import dev.whyoleg.cryptography.serialization.asn1.modules.RsaPublicKey
 import dev.whyoleg.cryptography.serialization.asn1.modules.SubjectPublicKeyInfo
+import kotlinx.serialization.json.Json
 
 /**
  * Computes the base64url-encoded SHA-256 hash of this JWK Thumbprint as defined by RFC 7638.
  *
  * @return The base64url-encoded SHA-256 digest of the canonical JSON representation of this thumbprint.
  */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Thumbprint.hashed(): String {
-    val bytes = JwtJson.encodeToString(this).encodeToByteArray()
+public suspend fun Jwk.Thumbprint.hashed(
+    jsonInstance: Json = JwtJson,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): String {
+    val bytes = jsonInstance.encodeToString(this).encodeToByteArray()
     val hash =
-        CryptographyProvider.Default
+        cryptoProvider
             .get(SHA256)
             .hasher()
             .hash(bytes)
@@ -52,8 +56,11 @@ public suspend fun Jwk.Thumbprint.hashed(): String {
  * Converts this [Jwk.Oct] to an [HMAC.Key] for the given [digest].
  */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Oct.toHmacKey(digest: CryptographyAlgorithmId<Digest>): HMAC.Key =
-    CryptographyProvider.Default
+public suspend fun Jwk.Oct.toHmacKey(
+    digest: CryptographyAlgorithmId<Digest>,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): HMAC.Key =
+    cryptoProvider
         .get(HMAC)
         .keyDecoder(digest)
         .decodeFromByteArray(HMAC.Key.Format.RAW, k.decodeBase64Url())
@@ -120,48 +127,66 @@ private fun Jwk.Rsa.toPkcs8Der(): ByteArray {
 
 /** Converts to [RSA.PKCS1.PublicKey] for RS256/RS384/RS512 verification. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Rsa.toRsaPkcs1PublicKey(digest: CryptographyAlgorithmId<Digest>): RSA.PKCS1.PublicKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Rsa.toRsaPkcs1PublicKey(
+    digest: CryptographyAlgorithmId<Digest>,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): RSA.PKCS1.PublicKey =
+    cryptoProvider
         .get(RSA.PKCS1)
         .publicKeyDecoder(digest)
         .decodeFromByteArray(RSA.PublicKey.Format.DER, toSpkiDer())
 
 /** Converts to [RSA.PKCS1.PrivateKey] for RS256/RS384/RS512 signing. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Rsa.toRsaPkcs1PrivateKey(digest: CryptographyAlgorithmId<Digest>): RSA.PKCS1.PrivateKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Rsa.toRsaPkcs1PrivateKey(
+    digest: CryptographyAlgorithmId<Digest>,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): RSA.PKCS1.PrivateKey =
+    cryptoProvider
         .get(RSA.PKCS1)
         .privateKeyDecoder(digest)
         .decodeFromByteArray(RSA.PrivateKey.Format.DER, toPkcs8Der())
 
 /** Converts to [RSA.PSS.PublicKey] for PS256/PS384/PS512 verification. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Rsa.toRsaPssPublicKey(digest: CryptographyAlgorithmId<Digest>): RSA.PSS.PublicKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Rsa.toRsaPssPublicKey(
+    digest: CryptographyAlgorithmId<Digest>,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): RSA.PSS.PublicKey =
+    cryptoProvider
         .get(RSA.PSS)
         .publicKeyDecoder(digest)
         .decodeFromByteArray(RSA.PublicKey.Format.DER, toSpkiDer())
 
 /** Converts to [RSA.PSS.PrivateKey] for PS256/PS384/PS512 signing. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Rsa.toRsaPssPrivateKey(digest: CryptographyAlgorithmId<Digest>): RSA.PSS.PrivateKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Rsa.toRsaPssPrivateKey(
+    digest: CryptographyAlgorithmId<Digest>,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): RSA.PSS.PrivateKey =
+    cryptoProvider
         .get(RSA.PSS)
         .privateKeyDecoder(digest)
         .decodeFromByteArray(RSA.PrivateKey.Format.DER, toPkcs8Der())
 
 /** Converts to [RSA.OAEP.PublicKey] for RSA-OAEP / RSA-OAEP-256 key encryption. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Rsa.toRsaOaepPublicKey(digest: CryptographyAlgorithmId<Digest>): RSA.OAEP.PublicKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Rsa.toRsaOaepPublicKey(
+    digest: CryptographyAlgorithmId<Digest>,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): RSA.OAEP.PublicKey =
+    cryptoProvider
         .get(RSA.OAEP)
         .publicKeyDecoder(digest)
         .decodeFromByteArray(RSA.PublicKey.Format.DER, toSpkiDer())
 
 /** Converts to [RSA.OAEP.PrivateKey] for RSA-OAEP / RSA-OAEP-256 key decryption. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Rsa.toRsaOaepPrivateKey(digest: CryptographyAlgorithmId<Digest>): RSA.OAEP.PrivateKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Rsa.toRsaOaepPrivateKey(
+    digest: CryptographyAlgorithmId<Digest>,
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): RSA.OAEP.PrivateKey =
+    cryptoProvider
         .get(RSA.OAEP)
         .privateKeyDecoder(digest)
         .decodeFromByteArray(RSA.PrivateKey.Format.DER, toPkcs8Der())
@@ -239,16 +264,20 @@ private fun Jwk.Ec.toPkcs8Der(): ByteArray {
 
 /** Converts to [ECDSA.PublicKey] for ES256/ES384/ES512 verification. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Ec.toEcdsaPublicKey(): ECDSA.PublicKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Ec.toEcdsaPublicKey(
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): ECDSA.PublicKey =
+    cryptoProvider
         .get(ECDSA)
         .publicKeyDecoder(ecCurve(crv))
         .decodeFromByteArray(EC.PublicKey.Format.DER, toSpkiDer())
 
 /** Converts to [ECDSA.PrivateKey] for ES256/ES384/ES512 signing. */
 @ExperimentalKJWTApi
-public suspend fun Jwk.Ec.toEcdsaPrivateKey(): ECDSA.PrivateKey =
-    CryptographyProvider.Default
+public suspend fun Jwk.Ec.toEcdsaPrivateKey(
+    cryptoProvider: CryptographyProvider = CryptographyProvider.Default,
+): ECDSA.PrivateKey =
+    cryptoProvider
         .get(ECDSA)
         .privateKeyDecoder(ecCurve(crv))
         .decodeFromByteArray(EC.PrivateKey.Format.DER, toPkcs8Der())

lib/src/commonMain/kotlin/co/touchlab/kjwt/internal/JsonUtils.kt

@@ -3,6 +3,8 @@ package co.touchlab.kjwt.internal
 import co.touchlab.kjwt.exception.MalformedJwtException
 import kotlinx.serialization.DeserializationStrategy
 import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.encodeToJsonElement
 
 @PublishedApi
 internal val JwtJson: Json =
@@ -34,6 +36,9 @@ internal fun <T> Json.decodeBase64Url(
 }
 
 internal inline fun <reified T> Json.encodeToBase64Url(value: T): String =
-    encodeToString(value)
+    encodeToJsonElement(value).encodeToBase64Url()
+
+internal fun JsonElement.encodeToBase64Url(): String =
+    toString()
         .encodeToByteArray()
         .encodeBase64Url()