Add ABI checking and other slight improvements.

Author: atholbro

.api-validation/paseto.api

@@ -12,13 +12,20 @@ plugins {
     alias(libs.plugins.gradleVersions)
     alias(libs.plugins.gradleVersions.filter)
     alias(libs.plugins.gradleVersions.update)
+    alias(libs.plugins.binaryCompatibilityValidator)
 }
 
 repositories {
     mavenLocal()
     mavenCentral()
 }
 
+apiValidation {
+    apiDumpDirectory = ".api-validation"
+    nonPublicMarkers += "net.aholbrook.paseto.InternalApi"
+    ignoredProjects.addAll(listOf("vector-gen"))
+}
+
 allprojects {
     apply(plugin = "java")
     apply(plugin = "org.jmailen.kotlinter")
@@ -78,3 +85,7 @@ allprojects {
         config.setFrom(files("${project.rootDir}/detekt-config.yml"))
     }
 }
+
+tasks.check {
+    dependsOn(tasks.apiCheck)
+}

build.gradle.kts

@@ -1,4 +1,5 @@
 [versions]
+binaryCompatibilityValidator = "0.18.1"
 bouncycastle = "1.83"
 clikt = "5.1.0"
 detekt = "1.23.8"
@@ -30,6 +31,7 @@ kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serializa
 mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
 
 [plugins]
+binaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binaryCompatibilityValidator" }
 detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
 gradleVersions = { id = "com.github.ben-manes.versions", version.ref = "gradleVersions" }
 gradleVersions-filter = { id = "se.ascp.gradle.gradle-versions-filter", version.ref = "gradleFilterVersions" }

gradle/libs.versions.toml

@@ -60,3 +60,9 @@ update-check:
 # Automatically updates all dependencies in the version catalog.
 update-apply:
     {{gradlew}} versionCatalogUpdate
+
+api-check:
+    {{gradlew}} apiCheck
+
+api-dump:
+    {{gradlew}} apiDump

justfile

@@ -42,6 +42,10 @@ tasks {
         options.release.set(17)
     }
 
+    withType<AbstractPublishToMaven>().configureEach {
+        dependsOn(rootProject.tasks.named("check"))
+    }
+
     withType<AbstractArchiveTask>().configureEach {
         isPreserveFileTimestamps = false
         isReproducibleFileOrder = true

paseto/.api-validation/paseto.api

@@ -0,0 +1,19 @@
+package net.aholbrook.paseto
+
+@DslMarker
+internal annotation class PasetoDslMarker
+
+@RequiresOptIn(
+    message = "This is an internal Paseto API and subject to change without notice.",
+    level = RequiresOptIn.Level.ERROR,
+)
+@Retention(AnnotationRetention.BINARY)
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY,
+    AnnotationTarget.FIELD,
+    AnnotationTarget.TYPEALIAS,
+    AnnotationTarget.CONSTRUCTOR,
+)
+annotation class Annotations

paseto/build.gradle.kts

@@ -69,6 +69,7 @@ value class ClaimPrimitive internal constructor(internal val primitive: JsonPrim
     override fun toString(): String = primitive.toString()
 }
 
+@PasetoDslMarker
 class ClaimObjectBuilder @PublishedApi internal constructor() {
     private val content: MutableMap<String, ClaimElement> = linkedMapOf()
 
@@ -91,6 +92,7 @@ inline fun claimObject(init: ClaimObjectBuilder.() -> Unit): ClaimObject {
     return builder.build()
 }
 
+@PasetoDslMarker
 class ClaimArrayBuilder @PublishedApi internal constructor() {
     private val content: MutableList<ClaimElement> = mutableListOf()
 

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

@@ -21,6 +21,7 @@ data class PasetoToken internal constructor(
     val footer: PasetoFooter?,
 )
 
+@PasetoDslMarker
 class PasetoTokenBuilder @PublishedApi internal constructor(clock: Clock) {
     var issuer: String? = null // iss
     var subject: String? = null // sub
@@ -64,6 +65,7 @@ data class ClaimFooter internal constructor(
     val claims: ClaimObject,
 ) : PasetoFooter
 
+@PasetoDslMarker
 class ClaimFooterBuilder @PublishedApi internal constructor() {
     var keyId: String? = null // kid
     var wrappedKey: String? = null // wpk
@@ -116,4 +118,12 @@ fun PasetoFooter?.taint(): TaintedPasetoFooter? = when (this) {
     is StringFooter -> TaintedStringFooter(value)
 }
 
+/**
+ * Escape hatch for direct access to the token's 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.
+ */
+
+@Annotations
 fun PasetoToken.claimsJson(): JsonObject = claims.toJson() as JsonObject

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

@@ -24,6 +24,7 @@ sealed interface Purpose {
     class Local(val keyProvider: () -> SymmetricKey) : Purpose
 }
 
+@PasetoDslMarker
 class TokenServiceBuilder @PublishedApi internal constructor() {
     var rules: Rules = rules()