Add kdocs.

Author: atholbro

paseto/src/main/kotlin/net/aholbrook/paseto/Claims.kt

@@ -14,6 +14,20 @@ import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
+/**
+ * Marker type for custom claim values.
+ *
+ * Claims can be represented as objects, arrays, primitives, or null.
+ *
+ * @property objectOrNull Value as [ClaimObject] when object-typed.
+ * @property arrayOrNull Value as [ClaimArray] when array-typed.
+ * @property primitiveOrNull Value as [ClaimPrimitive] when primitive-typed.
+ * @property stringOrNull Primitive string value if present.
+ * @property booleanOrNull Primitive boolean value if present.
+ * @property intOrNull Primitive int value if present.
+ * @property longOrNull Primitive long value if present.
+ * @property doubleOrNull Primitive double value if present.
+ */
 sealed interface ClaimElement {
     val objectOrNull: ClaimObject? get() = this as? ClaimObject
     val arrayOrNull: ClaimArray? get() = this as? ClaimArray
@@ -26,6 +40,15 @@ sealed interface ClaimElement {
     val doubleOrNull: Double? get() = null
 }
 
+/**
+ * Attempt to read this claim as a supported Kotlin type.
+ *
+ * Supported types are: [String], [Boolean], [Int], [Long], [Double], [ClaimObject],
+ * and [ClaimArray]. Calling with an unsupported type will return `null`.
+ *
+ * @receiver Claim element to cast.
+ * @return Cast value or `null` if unsupported/unmatched.
+ */
 inline fun <reified T> ClaimElement.asType(): T? = when (T::class) {
     String::class -> primitiveOrNull?.stringOrNull as? T
     Boolean::class -> primitiveOrNull?.booleanOrNull as? T
@@ -37,10 +60,12 @@ inline fun <reified T> ClaimElement.asType(): T? = when (T::class) {
     else -> null
 }
 
+/** Null claim value. */
 object ClaimNull : ClaimElement
 
 @JvmInline
 @Suppress("JavaDefaultMethodsNotOverriddenByDelegation")
+/** Array claim value. */
 value class ClaimArray internal constructor(private val content: List<ClaimElement>) :
     ClaimElement,
     List<ClaimElement> by content {
@@ -49,6 +74,7 @@ value class ClaimArray internal constructor(private val content: List<ClaimEleme
 }
 
 @JvmInline
+/** Object claim value. */
 value class ClaimObject internal constructor(private val content: Map<String, ClaimElement>) :
     ClaimElement,
     Map<String, ClaimElement> by content {
@@ -60,6 +86,7 @@ value class ClaimObject internal constructor(private val content: Map<String, Cl
 }
 
 @JvmInline
+/** Primitive claim value. */
 value class ClaimPrimitive internal constructor(internal val primitive: JsonPrimitive) : ClaimElement {
     override val stringOrNull: String? get() = primitive.contentOrNull?.takeIf { primitive.isString }
     override val booleanOrNull: Boolean? get() = primitive.booleanOrNull
@@ -70,19 +97,61 @@ value class ClaimPrimitive internal constructor(internal val primitive: JsonPrim
 }
 
 @PasetoDslMarker
+/** DSL Builder for [ClaimObject]. */
 class ClaimObjectBuilder @PublishedApi internal constructor() {
     private val content: MutableMap<String, ClaimElement> = linkedMapOf()
 
+    /**
+     * Put a nested claim value.
+     *
+     * @param key Claim key.
+     * @param value Claim value.
+     * @return Previous value for [key], if present.
+     */
     fun put(key: String, value: ClaimElement): ClaimElement? = content.put(key, value)
+    /**
+     * Put a boolean claim value.
+     *
+     * @param key Claim key.
+     * @param value Claim value.
+     * @return Previous value for [key], if present.
+     */
     fun put(key: String, value: Boolean): ClaimElement? = content.put(key, primitiveValue(value))
+    /**
+     * Put a numeric claim value.
+     *
+     * @param key Claim key.
+     * @param value Claim value.
+     * @return Previous value for [key], if present.
+     */
     fun put(key: String, value: Number): ClaimElement? = content.put(key, primitiveValue(value))
+    /**
+     * Put a string claim value.
+     *
+     * @param key Claim key.
+     * @param value Claim value.
+     * @return Previous value for [key], if present.
+     */
     fun put(key: String, value: String): ClaimElement? = content.put(key, primitiveValue(value))
+    /**
+     * Put a `null` claim value.
+     *
+     * @param key Claim key.
+     * @param value Claim value.
+     * @return Previous value for [key], if present.
+     */
     fun put(key: String, value: Nothing?): ClaimElement? = content.put(key, primitiveValue(value))
 
     @PublishedApi
     internal fun build(): ClaimObject = ClaimObject(content)
 }
 
+/**
+ * Build a [ClaimObject] using the claim DSL.
+ *
+ * @param init Claim-object builder block.
+ * @return Built [ClaimObject].
+ */
 @OptIn(ExperimentalContracts::class)
 inline fun claimObject(init: ClaimObjectBuilder.() -> Unit): ClaimObject {
     contract { callsInPlace(init, InvocationKind.EXACTLY_ONCE) }
@@ -93,19 +162,56 @@ inline fun claimObject(init: ClaimObjectBuilder.() -> Unit): ClaimObject {
 }
 
 @PasetoDslMarker
+/** DSL builder for [ClaimArray]. */
 class ClaimArrayBuilder @PublishedApi internal constructor() {
     private val content: MutableList<ClaimElement> = mutableListOf()
 
+    /**
+     * Add a nested claim value.
+     *
+     * @param value Claim value to append.
+     * @return `true` when appended.
+     */
     fun add(value: ClaimElement): Boolean = content.add(value)
+    /**
+     * Add a boolean value.
+     *
+     * @param value Claim value to append.
+     * @return `true` when appended.
+     */
     fun add(value: Boolean): Boolean = content.add(primitiveValue(value))
+    /**
+     * Add a numeric value.
+     *
+     * @param value Claim value to append.
+     * @return `true` when appended.
+     */
     fun add(value: Number): Boolean = content.add(primitiveValue(value))
+    /**
+     * Add a string value.
+     *
+     * @param value Claim value to append.
+     * @return `true` when appended.
+     */
     fun add(value: String): Boolean = content.add(primitiveValue(value))
+    /**
+     * Add a `null` value.
+     *
+     * @param value Claim value to append.
+     * @return `true` when appended.
+     */
     fun add(value: Nothing?): Boolean = content.add(primitiveValue(value))
 
     @PublishedApi
     internal fun build(): ClaimArray = ClaimArray(content)
 }
 
+/**
+ * Build a [ClaimArray] using the claim DSL.
+ *
+ * @param init Array builder block.
+ * @return Built [ClaimArray].
+ */
 @OptIn(ExperimentalContracts::class)
 inline fun claimArray(init: ClaimArrayBuilder.() -> Unit): ClaimArray {
     contract { callsInPlace(init, InvocationKind.EXACTLY_ONCE) }
@@ -129,7 +235,31 @@ internal fun ClaimElement.toJson(): JsonElement = when (this) {
     is ClaimObject -> JsonObject(this.mapValues { it.value.toJson() })
 }
 
+/**
+ * Convert a nullable boolean into a [ClaimPrimitive].
+ *
+ * @param value Boolean value.
+ * @return Primitive claim.
+ */
 fun primitiveValue(value: Boolean?): ClaimPrimitive = ClaimPrimitive(JsonPrimitive(value))
+/**
+ * Convert a nullable number into a [ClaimPrimitive].
+ *
+ * @param value Number value.
+ * @return Primitive claim.
+ */
 fun primitiveValue(value: Number?): ClaimPrimitive = ClaimPrimitive(JsonPrimitive(value))
+/**
+ * Convert a nullable string into a [ClaimPrimitive].
+ *
+ * @param value String value.
+ * @return Primitive claim.
+ */
 fun primitiveValue(value: String?): ClaimPrimitive = ClaimPrimitive(JsonPrimitive(value))
+/**
+ * Convert nullable `Nothing` into a JSON null [ClaimPrimitive].
+ *
+ * @param value Null literal.
+ * @return Primitive claim.
+ */
 fun primitiveValue(value: Nothing?): ClaimPrimitive = ClaimPrimitive(JsonPrimitive(value))

paseto/src/main/kotlin/net/aholbrook/paseto/Footer.kt

@@ -5,24 +5,50 @@ import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
+/**
+ * Marker interface for supported token footer types.
+ */
 sealed interface Footer
 
+/**
+ * String footer value.
+ *
+ * @property value Footer text.
+ */
 @JvmInline
 value class StringFooter internal constructor(val value: String) : Footer
 
 @ConsistentCopyVisibility
+/**
+ * Structured footer with reserved `kid`/`wpk` fields plus arbitrary custom claims.
+ *
+ * @property keyId Optional key identifier (`kid`).
+ * @property wrappedKey Optional wrapped key value (`wpk`).
+ * @property claims Custom footer claims.
+ */
 data class ClaimFooter internal constructor(
     val keyId: String?, // kid
     val wrappedKey: String?, // wpk
     val claims: ClaimObject,
 ) : Footer
 
 @PasetoDslMarker
+/**
+ * DSL builder for [ClaimFooter].
+ *
+ * @property keyId Optional key identifier (`kid`).
+ * @property wrappedKey Optional wrapped key value (`wpk`).
+ */
 class ClaimFooterBuilder @PublishedApi internal constructor() {
     var keyId: String? = null // kid
     var wrappedKey: String? = null // wpk
     private var claims: ClaimObject = ClaimObject()
 
+    /**
+     * Replace footer custom claims using the claim-object DSL.
+     *
+     * @param init Claim-object builder block.
+     */
     @OptIn(ExperimentalContracts::class)
     fun claims(init: ClaimObjectBuilder.() -> Unit) {
         contract { callsInPlace(init, InvocationKind.EXACTLY_ONCE) }
@@ -32,6 +58,11 @@ class ClaimFooterBuilder @PublishedApi internal constructor() {
         claims = builder.build()
     }
 
+    /**
+     * Replace footer custom claims with an existing [ClaimObject].
+     *
+     * @param claims Claim object to store on the footer.
+     */
     fun claims(claims: ClaimObject) {
         this.claims = claims
     }
@@ -44,8 +75,20 @@ class ClaimFooterBuilder @PublishedApi internal constructor() {
     )
 }
 
+/**
+ * Create a plain [StringFooter].
+ *
+ * @param footer Footer text.
+ * @return A [StringFooter] value.
+ */
 fun footer(footer: String) = StringFooter(footer)
 
+/**
+ * Build a structured [ClaimFooter] using the footer DSL.
+ *
+ * @param init Footer builder block.
+ * @return A [ClaimFooter] value.
+ */
 @OptIn(ExperimentalContracts::class)
 inline fun footer(init: ClaimFooterBuilder.() -> Unit): ClaimFooter {
     contract { callsInPlace(init, InvocationKind.EXACTLY_ONCE) }
@@ -60,18 +103,30 @@ inline fun footer(init: ClaimFooterBuilder.() -> Unit): ClaimFooter {
  */
 sealed interface TaintedFooter
 
+/**
+ * Tainted string footer extracted without token verification.
+ *
+ * @property value Unverified footer text.
+ */
 @JvmInline
 value class TaintedStringFooter(val value: String) : TaintedFooter
 
 @ConsistentCopyVisibility
+/**
+ * Tainted claim footer extracted without token verification.
+ *
+ * @property keyId Optional unverified key identifier (`kid`).
+ * @property wrappedKey Optional unverified wrapped key value (`wpk`).
+ * @property claims Unverified footer claims.
+ */
 data class TaintedClaimFooter internal constructor(
     val keyId: String?, // kid
     val wrappedKey: String?, // wpk
     val claims: ClaimObject,
 ) : TaintedFooter
 
 /**
- * Converts a [Footer] to it's [TaintedFooter] variant.
+ * Converts a [Footer] to its [TaintedFooter] variant.
  *
  * This can be used to compare an [TaintedClaimFooter] against a [ClaimFooter] built using the [footer] builder.
  * @receiver A [Footer] instance to turn taint.
@@ -83,19 +138,23 @@ fun Footer.taint(): TaintedFooter = when (this) {
 }
 
 /**
- * Escape hatch for direct access to the footer's claims as a [JsonObject].
+ * Escape hatch for direct access to footer claims as a [JsonObject].
  *
  * This is an internal API because it couples the caller to the `kotlinx.serialization` JSON implementation.
  * It may change or be removed without notice if the underlying serialization strategy changes.
+ * @receiver Verified [ClaimFooter].
+ * @return Footer claims as a [JsonObject].
  */
 @InternalApi
 fun ClaimFooter.claimsJson(): JsonObject = claims.toJson() as JsonObject
 
 /**
- * Escape hatch for direct access to the footer's claims as a [JsonObject].
+ * Escape hatch for direct access to footer claims as a [JsonObject].
  *
  * This is an internal API because it couples the caller to the `kotlinx.serialization` JSON implementation.
  * It may change or be removed without notice if the underlying serialization strategy changes.
+ * @receiver Unverified [TaintedClaimFooter].
+ * @return Footer claims as a [JsonObject].
  */
 @InternalApi
 fun TaintedClaimFooter.claimsJson(): JsonObject = claims.toJson() as JsonObject

paseto/src/main/kotlin/net/aholbrook/paseto/FooterSerde.kt

@@ -54,11 +54,23 @@ internal data class FooterOptions(
     val maxKeys: Int = 512,
 )
 
+/**
+ * Builder for footer parsing and validation settings used by [TokenServiceBuilder.footerOptions].
+ *
+ * @property parseMode Footer decode strategy, see [FooterParseMode].
+ * @property maxLength Maximum footer length in characters.
+ * @property maxDepth Maximum JSON nesting depth for object-like footers.
+ * @property maxKeys Maximum JSON key count for object-like footers.
+ */
 @PasetoDslMarker
 class FooterOptionsBuilder @PublishedApi internal constructor() {
+    /** Strategy used to decode footer text (`AUTO`, `CLAIMS`, or `STRING`). */
     var parseMode: FooterParseMode = FooterParseMode.AUTO
+    /** Maximum allowed footer string length in characters. */
     var maxLength: Int = 8192
+    /** Maximum allowed JSON object/array nesting depth for object-like footers. */
     var maxDepth: Int = 2
+    /** Maximum allowed JSON key count for object-like footers. */
     var maxKeys: Int = 512
 
     internal fun build(): FooterOptions = FooterOptions(