detekt rules (#5)

* enable detekt rules for undocumented public classes and functions, enhance documentation,
fix CryptoScope

* remove pull request trigger from CodeQL workflow

Author: SaBie73

.github/workflows/codeql.yml

@@ -3,8 +3,6 @@ name: "CodeQL Analysis"
 on:
   push:
     branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
   schedule:
     - cron: '27 0 * * 2'
 

config/detekt/detekt.yml

@@ -14,11 +14,10 @@ complexity:
     active: false
 
 comments:
-  # FIXME: Activate before launch
   UndocumentedPublicClass:
-    active: false
+    active: true
   UndocumentedPublicFunction:
-    active: false
+    active: true
 
 naming:
   MatchingDeclarationName:

crypto-jvm-lib/src/main/kotlin/de/gematik/openhealth/crypto/internal/interop/NativeLoader.kt

@@ -30,6 +30,11 @@ private val hostArch =
         .trim()
         .replace(" ", "")
 
+/**
+ * Loads the native crypto library for the current platform.
+ *
+ * @throws UnsatisfiedLinkError if the library cannot be loaded.
+ */
 @Suppress("UnsafeDynamicallyLoadedCode")
 fun loadNativeLibrary() {
     try {

crypto/src/commonMain/kotlin/de/gematik/openhealth/crypto/CryptoScope.kt

@@ -51,6 +51,9 @@ abstract class CryptoScope {
      */
     fun CmacSpec.createCmac(secret: SecretKey): Cmac = nativeCreateCmac(this@CryptoScope, secret)
 
+    /**
+     * Creates a Hash instance.
+     */
     fun HashSpec.createHash(): Hash = nativeCreateHash(this@CryptoScope)
 
     /**
@@ -99,8 +102,8 @@ fun <R : Any?> useCrypto(block: CryptoScope.() -> R): R = nativeUseCrypto(block)
  * ensuring that all resources are properly closed or released afterward.
  */
 suspend fun <R : Any?> useCryptoAsync(block: suspend CryptoScope.() -> R): R =
-    nativeUseCrypto(block)
+    nativeUseCryptoSuspendable(block)
 
 internal expect fun <R : Any?> nativeUseCrypto(block: CryptoScope.() -> R): R
 
-internal expect suspend fun <R : Any?> nativeUseCrypto(block: suspend CryptoScope.() -> R): R
+internal expect suspend fun <R : Any?> nativeUseCryptoSuspendable(block: suspend CryptoScope.() -> R): R

crypto/src/commonMain/kotlin/de/gematik/openhealth/crypto/kem/Kem.kt

@@ -89,6 +89,9 @@ data class KemDecapsulationResult(
 interface KemEncapsulation {
     val spec: KemSpec
 
+    /**
+     * Encapsulates a key and returns the shared secret and wrapped key.
+     */
     fun encapsulate(): KemEncapsulationResult
 }
 
@@ -99,8 +102,14 @@ interface KemEncapsulation {
 interface KemDecapsulation {
     val spec: KemSpec
 
+    /**
+     * Returns the encapsulation key.
+     */
     fun encapsulationKey(): ByteArray
 
+    /**
+     * Decapsulates the wrapped key and returns the shared secret.
+     */
     fun decapsulate(wrappedKey: ByteArray): KemDecapsulationResult
 }
 

crypto/src/commonMain/kotlin/de/gematik/openhealth/crypto/key/EcKey.kt

@@ -168,6 +168,9 @@ enum class EcCurve(
 
     val g: EcPoint get() = EcPoint(this, x, y)
 
+    /**
+     * Creates a new EC point with the given x and y coordinates.
+     */
     fun point(
         x: BigInteger?,
         y: BigInteger?,
@@ -231,6 +234,7 @@ class EcPublicKey internal constructor(
 
     override fun toString(): String = "EcPublicKey(data=${data.contentToString()}, curve=$curve)"
 
+    @Suppress("UndocumentedPublicClass")
     companion object {
         const val OID: String = "1.2.840.10045.2.1"
     }
@@ -354,6 +358,7 @@ class EcPrivateKey internal constructor(
 
     override fun toString(): String = "EcPrivateKey(data=${data.contentToString()}, curve=$curve)"
 
+    @Suppress("UndocumentedPublicClass")
     companion object
 }
 
@@ -395,6 +400,9 @@ fun EcPrivateKey.encodeToAsn1(): ByteArray =
         }
     }
 
+/**
+ * Encodes the private key as a PEM-encoded string.
+ */
 fun EcPrivateKey.encodeToPem(): String =
     Pem(type = "EC PRIVATE KEY", data = encodeToAsn1()).encodeToString()
 

crypto/src/commonMain/kotlin/de/gematik/openhealth/crypto/key/EcPoint.kt

@@ -92,16 +92,28 @@ data class EcPoint(
      */
     val isInfinity: Boolean get() = x == null && y == null
 
+    /**
+     * Adds this EC point to another EC point.
+     */
     operator fun plus(other: EcPoint): EcPoint = nativePlus(other)
 
+    /**
+     * Multiplies this EC point by a scalar value.
+     */
     operator fun times(k: BigInteger): EcPoint = nativeTimes(k)
 
+    /**
+     * Negates this EC point.
+     */
     fun negate(): EcPoint = if (isInfinity) this else curve.point(x, (curve.p - y!!).mod(curve.p))
 }
 
 internal expect fun EcPoint.nativeTimes(k: BigInteger): EcPoint
 
 internal expect fun EcPoint.nativePlus(other: EcPoint): EcPoint
 
+/**
+ * Converts this [EcPoint] to an [EcPublicKey].
+ */
 @ExperimentalCryptoApi
 fun EcPoint.toEcPublicKey(): EcPublicKey = EcPublicKey(curve, uncompressed)

crypto/src/commonMain/kotlin/de/gematik/openhealth/crypto/key/Key.kt

@@ -21,18 +21,24 @@ import de.gematik.openhealth.crypto.ExperimentalCryptoApi
 import de.gematik.openhealth.crypto.bytes
 import kotlin.js.JsExport
 
+/**
+ * Represents a key in the cryptographic system.
+ */
 @JsExport
 @ExperimentalCryptoApi
 interface Key {
     val data: ByteArray
 }
 
+/**
+ * Represents a secret key in the cryptographic system.
+ */
 @JsExport
 @ExperimentalCryptoApi
 class SecretKey(
     override val data: ByteArray,
 ) : Key {
-    val length: ByteUnit = data.size.bytes
+    private val length: ByteUnit = data.size.bytes
 
     override fun equals(other: Any?): Boolean {
         if (this === other) return true

crypto/src/commonTest/kotlin/de/gematik/openhealth/crypto/key/EcPointBrainpoolP384r1Test.kt

@@ -5,7 +5,7 @@ import de.gematik.openhealth.crypto.runTestWithProvider
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
-@Suppress("ktlint:standard:max-line-length", "MaxLineLength", "LongMethod")
+@Suppress("MaxLineLength", "LongMethod")
 class EcPointBrainpoolP384r1Test {
     private val curve = EcCurve.BrainpoolP384r1
 

crypto/src/commonTest/kotlin/de/gematik/openhealth/crypto/key/EcPointBrainpoolP512r1Test.kt

@@ -5,7 +5,7 @@ import de.gematik.openhealth.crypto.runTestWithProvider
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
-@Suppress("ktlint:standard:max-line-length", "MaxLineLength", "LongMethod")
+@Suppress("MaxLineLength", "LongMethod")
 class EcPointBrainpoolP512r1Test {
     private val curve = EcCurve.BrainpoolP512r1