Adding kdocs

Author: faogustavo

build-logic/src/main/kotlin/kjwt/docs.kt

@@ -26,6 +26,9 @@ fun DokkaSourceSetSpec.registerExternalDocumentation() {
     externalDocumentationLinks.register("cryptography-kotlin") {
         url("https://whyoleg.github.io/cryptography-kotlin/api/")
     }
+    externalDocumentationLinks.register("kotlinx-serialization") {
+        url("https://kotlinlang.org/api/kotlinx.serialization/")
+    }
 }
 
 fun DokkaExtension.registerVersioningPlugin(project: Project) {

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

@@ -41,35 +41,147 @@ public class JwtBuilder {
     internal val payloadBuilder: JwtPayload.Builder = JwtPayload.Builder()
     private val headerBuilder: JwtHeader.Builder = JwtHeader.Builder()
 
+    /**
+     * Sets the issuer (`iss`) claim.
+     *
+     * @param iss the issuer identifier
+     * @return this builder for chaining
+     */
     public fun issuer(iss: String): JwtBuilder = apply { payloadBuilder.issuer = iss }
+
+    /**
+     * Sets the subject (`sub`) claim.
+     *
+     * @param sub the subject identifier
+     * @return this builder for chaining
+     */
     public fun subject(sub: String): JwtBuilder = apply { payloadBuilder.subject = sub }
+
+    /**
+     * Sets the audience (`aud`) claim.
+     *
+     * @param aud one or more audience identifiers
+     * @return this builder for chaining
+     */
     public fun audience(vararg aud: String): JwtBuilder = apply { payloadBuilder.audience = aud.toSet() }
+
+    /**
+     * Sets the expiration time (`exp`) claim.
+     *
+     * @param exp the absolute instant at which the token expires
+     * @return this builder for chaining
+     */
     public fun expiration(exp: Instant): JwtBuilder = apply { payloadBuilder.expiration = exp }
+
+    /**
+     * Sets the expiration time (`exp`) claim relative to the current time.
+     *
+     * @param duration the duration from now until the token expires
+     * @return this builder for chaining
+     */
     public fun expiresIn(duration: Duration): JwtBuilder = apply { payloadBuilder.expiresIn(duration) }
+
+    /**
+     * Sets the not-before (`nbf`) claim.
+     *
+     * @param nbf the absolute instant before which the token must not be accepted
+     * @return this builder for chaining
+     */
     public fun notBefore(nbf: Instant): JwtBuilder = apply { payloadBuilder.notBefore = nbf }
+
+    /**
+     * Sets the not-before (`nbf`) claim to the current time.
+     *
+     * @return this builder for chaining
+     */
     public fun notBeforeNow(): JwtBuilder = apply { payloadBuilder.notBeforeNow() }
+
+    /**
+     * Sets the issued-at (`iat`) claim.
+     *
+     * @param iat the instant at which the token was issued
+     * @return this builder for chaining
+     */
     public fun issuedAt(iat: Instant): JwtBuilder = apply { payloadBuilder.issuedAt = iat }
+
+    /**
+     * Sets the issued-at (`iat`) claim to the current time.
+     *
+     * @return this builder for chaining
+     */
     public fun issuedNow(): JwtBuilder = apply { payloadBuilder.issuedNow() }
+
+    /**
+     * Sets the JWT ID (`jti`) claim.
+     *
+     * @param jti the unique identifier for this token
+     * @return this builder for chaining
+     */
     public fun id(jti: String): JwtBuilder = apply { payloadBuilder.id = jti }
 
+    /**
+     * Sets the JWT ID (`jti`) claim to a randomly generated UUID.
+     *
+     * @return this builder for chaining
+     */
     @ExperimentalUuidApi
     public fun randomId(): JwtBuilder = apply { payloadBuilder.randomId() }
 
+    /**
+     * Sets a raw claim using a pre-built [JsonElement].
+     *
+     * @param name the claim name
+     * @param value the claim value as a [JsonElement]
+     * @return this builder for chaining
+     */
     public fun claim(name: String, value: JsonElement): JwtBuilder =
         apply { payloadBuilder.claim(name, value) }
 
+    /**
+     * Sets a typed claim using an explicit [SerializationStrategy].
+     *
+     * @param name the claim name
+     * @param serializer the serialization strategy for [T]
+     * @param value the claim value, or `null` to remove the claim
+     * @return this builder for chaining
+     */
     public fun <T> claim(name: String, serializer: SerializationStrategy<T>, value: T?): JwtBuilder =
         apply { payloadBuilder.claim(name, serializer, value) }
 
+    /**
+     * Sets a typed claim, inferring the serializer from the reified type [T].
+     *
+     * @param name the claim name
+     * @param value the claim value
+     * @return this builder for chaining
+     */
     public inline fun <reified T> claim(name: String, value: T): JwtBuilder =
         apply { payloadBuilder.claim(name, value) }
 
+    /**
+     * Configures multiple claims at once using a DSL block applied to [JwtPayload.Builder].
+     *
+     * @param block the configuration block
+     * @return this builder for chaining
+     */
     public fun claims(block: JwtPayload.Builder.() -> Unit): JwtBuilder =
         apply { payloadBuilder.block() }
 
+    /**
+     * Configures JOSE header fields using a DSL block applied to [JwtHeader.Builder].
+     *
+     * @param block the configuration block
+     * @return this builder for chaining
+     */
     public fun header(block: JwtHeader.Builder.() -> Unit): JwtBuilder =
         apply { headerBuilder.block() }
 
+    /**
+     * Sets the key ID (`kid`) header parameter.
+     *
+     * @param kid the key identifier
+     * @return this builder for chaining
+     */
     public fun keyId(kid: String): JwtBuilder =
         apply { headerBuilder.keyId = kid }
 
@@ -91,6 +203,13 @@ public class JwtBuilder {
         return JwtInstance.Jws(header, payload, signature.encodeBase64Url())
     }
 
+    /**
+     * Builds and returns an unsecured JWS token with `alg=none` and an empty signature.
+     *
+     * @param algorithm the [SigningAlgorithm.None] sentinel value
+     * @return the resulting [JwtInstance.Jws] with an empty signature segment
+     * @see co.touchlab.kjwt.parser.JwtParserBuilder.allowUnsecured
+     */
     public suspend fun signWith(algorithm: SigningAlgorithm.None): JwtInstance.Jws =
         signWith(algorithm, SimpleKey.Empty)
 

lib/src/commonMain/kotlin/co/touchlab/kjwt/cryptography/SimpleKey.kt

@@ -4,8 +4,15 @@ import dev.whyoleg.cryptography.CryptographyProviderApi
 import dev.whyoleg.cryptography.materials.key.Key
 
 @OptIn(CryptographyProviderApi::class)
-public class SimpleKey(public val value: ByteArray) : Key {
+public class SimpleKey(
+    /** The raw key bytes that back this key material. */
+    public val value: ByteArray,
+) : Key {
     public companion object {
+        /**
+         * An empty (zero-length) key singleton, used as a placeholder for direct-key (`dir`) JWE encryption where no
+         * wrapping key is needed.
+         */
         public val Empty: SimpleKey = SimpleKey(ByteArray(0))
     }
 }

lib/src/commonMain/kotlin/co/touchlab/kjwt/exception/JwtException.kt

@@ -3,38 +3,66 @@ package co.touchlab.kjwt.exception
 import co.touchlab.kjwt.model.JwtHeader
 import co.touchlab.kjwt.model.JwtPayload
 
+/** Base class for all exceptions thrown by the KJWT library. */
 public open class JwtException(message: String, cause: Throwable? = null) : Exception(message, cause)
 
+/**
+ * Thrown when a JWT string is structurally invalid, such as having the wrong number of parts, containing invalid
+ * Base64URL encoding, or being unparseable as JSON.
+ */
 public class MalformedJwtException(message: String, cause: Throwable? = null) : JwtException(message, cause)
 
+/**
+ * Thrown when a JWK JSON object is structurally invalid or is missing one or more required fields needed to
+ * reconstruct the key.
+ */
 public class MalformedJwkException(message: String, cause: Throwable? = null) : JwtException(message, cause)
 
+/**
+ * Thrown when signature verification of a JWS token fails or when decryption of a JWE token fails, indicating the
+ * token may have been tampered with or was encrypted with a different key.
+ */
 public class SignatureException(message: String, cause: Throwable? = null) : JwtException(message, cause)
 
+/** Thrown when a token uses an algorithm, key type, or feature that is not supported by this library. */
 public class UnsupportedJwtException(message: String, cause: Throwable? = null) : JwtException(message, cause)
 
+/** Thrown when a JWT's `exp` (expiration time) claim indicates the token has already expired. */
 public class ExpiredJwtException(
+    /** The header of the expired token. */
     public val header: JwtHeader,
+    /** The claims of the expired token whose `exp` value has passed. */
     public val claims: JwtPayload,
     message: String,
 ) : JwtException(message)
 
+/** Thrown when a JWT's `nbf` (not-before) claim indicates the token is not yet valid. */
 public class PrematureJwtException(
+    /** The header of the premature token. */
     public val header: JwtHeader,
+    /** The claims of the premature token whose `nbf` value has not yet been reached. */
     public val claims: JwtPayload,
     message: String,
 ) : JwtException(message)
 
+/** Thrown when a required claim is absent from the token's payload. */
 public class MissingClaimException(
+    /** The name of the required claim that was absent from the token. */
     public val claimName: String,
 ) : JwtException("Missing required claim: '$claimName'")
 
+/** Thrown when a required header parameter is absent from the token's header. */
 public class MissingHeaderException(
+    /** The name of the required header parameter that was absent from the token. */
     public val headerName: String,
 ) : JwtException("Missing required header: '$headerName'")
 
+/** Thrown when a claim is present in the token but its value does not match the expected value. */
 public class IncorrectClaimException(
+    /** The name of the claim whose value did not match. */
     public val claimName: String,
+    /** The expected value that the claim should have had. */
     public val expected: Any?,
+    /** The actual value found in the token for this claim. */
     public val actual: Any?,
 ) : JwtException("Claim '$claimName' expected '$expected' but was '$actual'")

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

@@ -11,34 +11,70 @@ import co.touchlab.kjwt.model.jwk.Jwk
 // signWith — HMAC (oct)
 // ---------------------------------------------------------------------------
 
+/**
+ * Signs the JWT using an HMAC key derived from the given [Jwk.Oct] symmetric JWK.
+ *
+ * @param algorithm The HMAC-based signing algorithm (HS256, HS384, or HS512).
+ * @param jwk The Oct JWK containing the raw symmetric key material.
+ * @return The signed [JwtInstance.Jws] token.
+ */
 public suspend fun JwtBuilder.signWith(algorithm: SigningAlgorithm.HashBased, jwk: Jwk.Oct): JwtInstance.Jws =
     signWith(algorithm, jwk.toHmacKey(algorithm.digest))
 
 // ---------------------------------------------------------------------------
 // signWith — RSA PKCS1 (RS*)
 // ---------------------------------------------------------------------------
 
+/**
+ * Signs the JWT using an RSA PKCS#1 private key derived from the given [Jwk.Rsa] JWK.
+ *
+ * @param algorithm The RSA PKCS#1-based signing algorithm (RS256, RS384, or RS512).
+ * @param jwk The RSA JWK containing the private key parameters.
+ * @return The signed [JwtInstance.Jws] token.
+ */
 public suspend fun JwtBuilder.signWith(algorithm: SigningAlgorithm.PKCS1Based, jwk: Jwk.Rsa): JwtInstance.Jws =
     signWith(algorithm, jwk.toRsaPkcs1PrivateKey(algorithm.digest))
 
 // ---------------------------------------------------------------------------
 // signWith — RSA PSS (PS*)
 // ---------------------------------------------------------------------------
 
+/**
+ * Signs the JWT using an RSA PSS private key derived from the given [Jwk.Rsa] JWK.
+ *
+ * @param algorithm The RSA PSS-based signing algorithm (PS256, PS384, or PS512).
+ * @param jwk The RSA JWK containing the private key parameters.
+ * @return The signed [JwtInstance.Jws] token.
+ */
 public suspend fun JwtBuilder.signWith(algorithm: SigningAlgorithm.PSSBased, jwk: Jwk.Rsa): JwtInstance.Jws =
     signWith(algorithm, jwk.toRsaPssPrivateKey(algorithm.digest))
 
 // ---------------------------------------------------------------------------
 // signWith — ECDSA (ES*)
 // ---------------------------------------------------------------------------
 
+/**
+ * Signs the JWT using an ECDSA private key derived from the given [Jwk.Ec] JWK.
+ *
+ * @param algorithm The ECDSA-based signing algorithm (ES256, ES384, or ES512).
+ * @param jwk The EC JWK containing the private key parameter `d`.
+ * @return The signed [JwtInstance.Jws] token.
+ */
 public suspend fun JwtBuilder.signWith(algorithm: SigningAlgorithm.ECDSABased, jwk: Jwk.Ec): JwtInstance.Jws =
     signWith(algorithm, jwk.toEcdsaPrivateKey())
 
 // ---------------------------------------------------------------------------
 // encryptWith — RSA-OAEP / RSA-OAEP-256
 // ---------------------------------------------------------------------------
 
+/**
+ * Encrypts the JWT using an RSA OAEP public key derived from the given [Jwk.Rsa] JWK.
+ *
+ * @param jwk The RSA JWK containing the public key parameters `n` and `e`.
+ * @param keyAlgorithm The OAEP-based key encryption algorithm (RSA-OAEP or RSA-OAEP-256).
+ * @param contentAlgorithm The content encryption algorithm to use for the JWE payload.
+ * @return The encrypted [JwtInstance.Jwe] token.
+ */
 @OptIn(dev.whyoleg.cryptography.DelicateCryptographyApi::class)
 public suspend fun JwtBuilder.encryptWith(
     jwk: Jwk.Rsa,

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

@@ -27,6 +27,11 @@ import dev.whyoleg.cryptography.serialization.asn1.modules.RsaPrivateKey
 import dev.whyoleg.cryptography.serialization.asn1.modules.RsaPublicKey
 import dev.whyoleg.cryptography.serialization.asn1.modules.SubjectPublicKeyInfo
 
+/**
+ * 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.
+ */
 public suspend fun Jwk.Thumbprint.hashed(): String {
     val bytes = JwtJson.encodeToString(this).encodeToByteArray()
     val hash = CryptographyProvider.Default.get(SHA256).hasher().hash(bytes)