added helper functions to construct jwt header and payload from serializable type

Author: faogustavo

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

@@ -181,6 +181,34 @@ public class JwtBuilder {
      */
     public fun claims(block: JwtPayload.Builder.() -> Unit): JwtBuilder = apply { payloadBuilder.block() }
 
+    /**
+     * Merges all fields from [value] into the payload, encoded using [serializer].
+     *
+     * The object is serialized to a JSON object and each key-value pair is added to the payload,
+     * overwriting any existing claim with the same name.
+     *
+     * @param serializer the serialization strategy for [T]
+     * @param value the object whose fields should be merged into the payload
+     * @return this builder for chaining
+     */
+    public fun <T> payload(
+        serializer: SerializationStrategy<T>,
+        value: T,
+    ): JwtBuilder = apply { payloadBuilder.takeFrom(serializer, value) }
+
+    /**
+     * Merges all fields from [value] into the payload, inferring the serializer from the reified
+     * type [T].
+     *
+     * The object is serialized to a JSON object and each key-value pair is added to the payload,
+     * overwriting any existing claim with the same name.
+     *
+     * @param value the object whose fields should be merged into the payload
+     * @return this builder for chaining
+     */
+    public inline fun <reified T> payload(value: T): JwtBuilder =
+        payload(kotlinx.serialization.serializer<T>(), value)
+
     /**
      * Sets the token type (`typ`) header parameter.
      *
@@ -243,6 +271,34 @@ public class JwtBuilder {
      */
     public fun header(block: JwtHeader.Builder.() -> Unit): JwtBuilder = apply { headerBuilder.block() }
 
+    /**
+     * Merges all fields from [value] into the JOSE header, encoded using [serializer].
+     *
+     * The object is serialized to a JSON object and each key-value pair is added to the header,
+     * overwriting any existing parameter with the same name.
+     *
+     * @param serializer the serialization strategy for [T]
+     * @param value the object whose fields should be merged into the header
+     * @return this builder for chaining
+     */
+    public fun <T> header(
+        serializer: SerializationStrategy<T>,
+        value: T,
+    ): JwtBuilder = apply { headerBuilder.takeFrom(serializer, value) }
+
+    /**
+     * Merges all fields from [value] into the JOSE header, inferring the serializer from the
+     * reified type [T].
+     *
+     * The object is serialized to a JSON object and each key-value pair is added to the header,
+     * overwriting any existing parameter with the same name.
+     *
+     * @param value the object whose fields should be merged into the header
+     * @return this builder for chaining
+     */
+    public inline fun <reified T> header(value: T): JwtBuilder =
+        header(kotlinx.serialization.serializer<T>(), value)
+
     /**
      * Builds and returns a JWS compact serialization: `header.payload.signature`.
      *

lib/src/commonMain/kotlin/co/touchlab/kjwt/model/JwtHeader.kt

@@ -162,6 +162,36 @@ public class JwtHeader internal constructor(
             extra(name, kotlinx.serialization.serializer<T>(), value)
         }
 
+        /**
+         * Merges all fields from [value] into this builder, encoded using [serializer].
+         *
+         * The object is serialized to a [JsonObject] and each key-value pair is added to the
+         * header, overwriting any existing parameter with the same name.
+         *
+         * @param serializer the serialization strategy for [T]
+         * @param value the object whose fields should be merged into the header
+         */
+        public fun <T> takeFrom(
+            serializer: SerializationStrategy<T>,
+            value: T,
+        ) {
+            val jsonObject = JwtJson.encodeToJsonElement(serializer, value) as JsonObject
+            jsonObject.forEach { (key, element) -> content[key] = element }
+        }
+
+        /**
+         * Merges all fields from [value] into this builder, inferring the serializer from the
+         * reified type [T].
+         *
+         * The object is serialized to a [JsonObject] and each key-value pair is added to the
+         * header, overwriting any existing parameter with the same name.
+         *
+         * @param value the object whose fields should be merged into the header
+         */
+        public inline fun <reified T> takeFrom(value: T) {
+            takeFrom(kotlinx.serialization.serializer<T>(), value)
+        }
+
         internal fun build(
             algorithm: SigningAlgorithm<*, *>,
             keyId: String?,

lib/src/commonMain/kotlin/co/touchlab/kjwt/model/JwtPayload.kt

@@ -191,6 +191,36 @@ public class JwtPayload internal constructor(
             claim(name, kotlinx.serialization.serializer<T>(), value)
         }
 
+        /**
+         * Merges all fields from [value] into this builder, encoded using [serializer].
+         *
+         * The object is serialized to a [JsonObject] and each key-value pair is added to the
+         * payload, overwriting any existing claim with the same name.
+         *
+         * @param serializer the serialization strategy for [T]
+         * @param value the object whose fields should be merged into the payload
+         */
+        public fun <T> takeFrom(
+            serializer: SerializationStrategy<T>,
+            value: T,
+        ) {
+            val jsonObject = JwtJson.encodeToJsonElement(serializer, value) as JsonObject
+            jsonObject.forEach { (key, element) -> content[key] = element }
+        }
+
+        /**
+         * Merges all fields from [value] into this builder, inferring the serializer from the
+         * reified type [T].
+         *
+         * The object is serialized to a [JsonObject] and each key-value pair is added to the
+         * payload, overwriting any existing claim with the same name.
+         *
+         * @param value the object whose fields should be merged into the payload
+         */
+        public inline fun <reified T> takeFrom(value: T) {
+            takeFrom(kotlinx.serialization.serializer<T>(), value)
+        }
+
         /**
          * Sets the expiration time (`exp`) claim relative to the current time.
          *

lib/src/commonTest/kotlin/co/touchlab/kjwt/JwtBuilderTakeFromTest.kt

@@ -0,0 +1,222 @@
+package co.touchlab.kjwt
+
+import co.touchlab.kjwt.ext.audience
+import co.touchlab.kjwt.ext.getClaim
+import co.touchlab.kjwt.ext.getClaimOrNull
+import co.touchlab.kjwt.ext.getHeader
+import co.touchlab.kjwt.ext.subject
+import co.touchlab.kjwt.ext.type
+import co.touchlab.kjwt.model.JwtHeader
+import co.touchlab.kjwt.model.JwtPayload
+import co.touchlab.kjwt.model.algorithm.EncryptionAlgorithm
+import co.touchlab.kjwt.model.algorithm.EncryptionContentAlgorithm
+import co.touchlab.kjwt.model.algorithm.SigningAlgorithm
+import io.kotest.core.spec.style.FunSpec
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.serializer
+import kotlin.test.assertEquals
+
+@Serializable private data class TakeFromPayload(
+    @SerialName(JwtPayload.SUB) val userId: String,
+    val role: String,
+)
+
+@Serializable private data class TakeFromHeader(
+    @SerialName(JwtHeader.TYP) val type: String,
+    val version: Int,
+)
+
+class JwtBuilderTakeFromTest :
+    FunSpec({
+        context("JwtBuilder.payload()") {
+            test("explicit serializer merges payload fields (JWS)") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .payload(serializer<TakeFromPayload>(), TakeFromPayload("u1", "admin"))
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("u1", jws.payload.subject)
+                assertEquals("admin", jws.payload.getClaim("role"))
+            }
+
+            test("reified generic merges payload fields (JWS)") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .payload(TakeFromPayload("u2", "viewer"))
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("u2", jws.payload.subject)
+                assertEquals("viewer", jws.payload.getClaim("role"))
+            }
+
+            test("payload() is additive — previously set claims survive") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .audience("prior-aud")
+                        .payload(TakeFromPayload("u3", "editor"))
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("prior-aud", jws.payload.audience.first())
+                assertEquals("u3", jws.payload.subject)
+                assertEquals("editor", jws.payload.getClaimOrNull("role"))
+            }
+
+            test("payload() is additive — existing keys are replaced") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .subject("sub")
+                        .payload(TakeFromPayload("u3", "editor"))
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("u3", jws.payload.subject)
+                assertEquals("editor", jws.payload.getClaimOrNull("role"))
+            }
+
+            test("values taken from another type can be replaced") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .payload(TakeFromPayload("u4", "editor"))
+                        .subject("sub")
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("sub", jws.payload.subject)
+                assertEquals("editor", jws.payload.getClaimOrNull("role"))
+            }
+
+            test("explicit serializer merges payload fields (JWE)") {
+                val cek = aesSimpleKey(256)
+                val token =
+                    Jwt.builder()
+                        .payload(serializer<TakeFromPayload>(), TakeFromPayload("u4", "guest"))
+                        .encryptWith(cek, EncryptionAlgorithm.Dir, EncryptionContentAlgorithm.A256GCM)
+                        .compact()
+
+                val jwe = Jwt.parser().decryptWith(EncryptionAlgorithm.Dir, cek).build().parseEncrypted(token)
+
+                assertEquals("u4", jwe.payload.subject)
+                assertEquals("guest", jwe.payload.getClaim("role"))
+            }
+        }
+
+        context("JwtBuilder.header()") {
+            test("explicit serializer merges header fields (JWS)") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .subject("user")
+                        .header(serializer<TakeFromHeader>(), TakeFromHeader("at+JWT", 2))
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("at+JWT", jws.header.type)
+                assertEquals(2, jws.header.getHeader<Int>("version"))
+            }
+
+            test("reified generic merges header fields (JWS)") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .subject("user")
+                        .header(TakeFromHeader("at+JWT", 3))
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("at+JWT", jws.header.type)
+                assertEquals(3, jws.header.getHeader<Int>("version"))
+            }
+
+            test("header() is additive — pre-existing parameters survive") {
+                val key = hs256Key()
+                val token =
+                    Jwt.builder()
+                        .subject("user")
+                        .contentType("JWT")
+                        .header(TakeFromHeader("at+JWT", 1))
+                        .signWith(SigningAlgorithm.HS256, key)
+                        .compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("JWT", jws.header.getHeader("cty"))
+                assertEquals("at+JWT", jws.header.type)
+                assertEquals(1, jws.header.getHeader<Int>("version"))
+            }
+        }
+
+        context("JwtPayload.Builder.takeFrom()") {
+            test("explicit serializer merges claims via DSL block") {
+                val key = hs256Key()
+                val token = Jwt.builder().claims {
+                    takeFrom(serializer<TakeFromPayload>(), TakeFromPayload("u5", "ops"))
+                }.signWith(SigningAlgorithm.HS256, key).compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("u5", jws.payload.subject)
+                assertEquals("ops", jws.payload.getClaim("role"))
+            }
+
+            test("reified generic merges claims via DSL block") {
+                val key = hs256Key()
+                val token = Jwt.builder().claims {
+                    takeFrom(TakeFromPayload("u6", "dev"))
+                }.signWith(SigningAlgorithm.HS256, key).compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("u6", jws.payload.subject)
+                assertEquals("dev", jws.payload.getClaim("role"))
+            }
+        }
+
+        context("JwtHeader.Builder.takeFrom()") {
+            test("explicit serializer merges header params via DSL block") {
+                val key = hs256Key()
+                val token = Jwt.builder().subject("user").header {
+                    takeFrom(serializer<TakeFromHeader>(), TakeFromHeader("at+JWT", 4))
+                }.signWith(SigningAlgorithm.HS256, key).compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("at+JWT", jws.header.type)
+                assertEquals(4, jws.header.getHeader<Int>("version"))
+            }
+
+            test("reified generic merges header params via DSL block") {
+                val key = hs256Key()
+                val token = Jwt.builder().subject("user").header {
+                    takeFrom(TakeFromHeader("at+JWT", 5))
+                }.signWith(SigningAlgorithm.HS256, key).compact()
+
+                val jws = Jwt.parser().verifyWith(SigningAlgorithm.HS256, key).build().parseSigned(token)
+
+                assertEquals("at+JWT", jws.header.type)
+                assertEquals(5, jws.header.getHeader<Int>("version"))
+            }
+        }
+    })