@cap-kit/ssl-pinning 8.0.0-next.0 → 8.0.0

package/android/src/main/java/io/capkit/sslpinning/SSLPinningConfig.kt

@@ -1,22 +1,67 @@
 package io.capkit.sslpinning
 
+import android.content.Context
 import com.getcapacitor.Plugin
 
+/**
+ * Plugin configuration container.
+ *
+ * This class is responsible for reading and exposing
+ * static configuration values defined under the
+ * `SSLPinning` key in capacitor.config.ts.
+ *
+ * Configuration rules:
+ * - Read once during plugin initialization
+ * - Treated as immutable runtime input
+ * - Accessible only from native code
+ */
 class SSLPinningConfig(plugin: Plugin) {
+  /**
+   * Android application context.
+   * Exposed for native components that may require it.
+   */
+  val context: Context = plugin.context
+
+  /**
+   * Enables verbose native logging.
+   *
+   * When enabled, additional debug information
+   * is printed to Logcat.
+   *
+   * Default: false
+   */
   val verboseLogging: Boolean
+
+  /**
+   * Default SHA-256 fingerprint used by checkCertificate()
+   * when no fingerprint is provided at runtime.
+   */
   val fingerprint: String?
+
+  /**
+   * Default SHA-256 fingerprints used by checkCertificates()
+   * when no fingerprints are provided at runtime.
+   */
   val fingerprints: List<String>
 
   init {
     val config = plugin.getConfig()
 
-    verboseLogging = config.getBoolean("verboseLogging", false)
+    // Verbose logging flag
+    verboseLogging =
+      config.getBoolean("verboseLogging", false)
 
+    // Single fingerprint (optional)
     val fp = config.getString("fingerprint")
-    fingerprint = if (fp.isNullOrBlank()) null else fp
+    fingerprint =
+      if (!fp.isNullOrBlank()) fp else null
 
+    // Multiple fingerprints (optional)
     fingerprints =
-      config.getArray("fingerprints")?.toList()?.mapNotNull { it as? String }
+      config.getArray("fingerprints")
+        ?.toList()
+        ?.mapNotNull { it as? String }
+        ?.filter { it.isNotBlank() }
         ?: emptyList()
   }
 }

package/android/src/main/java/io/capkit/sslpinning/SSLPinningError.kt

@@ -0,0 +1,40 @@
+package io.capkit.sslpinning
+
+/**
+ * Native error model for the SSLPinning plugin (Android).
+ *
+ * Architectural rules:
+ * - Must NOT reference Capacitor APIs
+ * - Must NOT reference JavaScript
+ * - Must be throwable from the Impl layer
+ * - Mapping to JS-facing error codes happens ONLY in the Plugin layer
+ */
+sealed class SSLPinningError(
+  message: String,
+) : Throwable(message) {
+  /**
+   * Feature or capability is not available
+   * due to device or configuration limitations.
+   */
+  class Unavailable(message: String) :
+    SSLPinningError(message)
+
+  /**
+   * Required permission was denied or not granted.
+   */
+  class PermissionDenied(message: String) :
+    SSLPinningError(message)
+
+  /**
+   * Plugin failed to initialize or perform
+   * a required operation.
+   */
+  class InitFailed(message: String) :
+    SSLPinningError(message)
+
+  /**
+   * Invalid or unsupported input was provided.
+   */
+  class UnknownType(message: String) :
+    SSLPinningError(message)
+}

package/android/src/main/java/io/capkit/sslpinning/SSLPinningImpl.kt

@@ -1,5 +1,6 @@
 package io.capkit.sslpinning
 
+import android.content.Context
 import io.capkit.sslpinning.utils.SSLPinningLogger
 import io.capkit.sslpinning.utils.SSLPinningUtils
 import java.net.URL
@@ -9,157 +10,191 @@ import javax.net.ssl.SSLContext
 import javax.net.ssl.TrustManager
 import javax.net.ssl.X509TrustManager
 
+/**
+ * Native Android implementation for the SSLPinning plugin.
+ *
+ * Responsibilities:
+ * - Perform platform-specific SSL pinning logic
+ * - Interact with system networking APIs
+ * - Throw typed SSLPinningError values on failure
+ *
+ * Forbidden:
+ * - Accessing PluginCall
+ * - Referencing Capacitor APIs
+ * - Constructing JavaScript payloads
+ */
 class SSLPinningImpl(
-  private val config: SSLPinningConfig,
+  private val context: Context,
 ) {
-  // ---- Single fingerprint ----
+  /**
+   * Cached plugin configuration.
+   * Injected once during plugin initialization.
+   */
+  private lateinit var config: SSLPinningConfig
 
   /**
-   * Validates the SSL certificate of a HTTPS endpoint using a single SHA-256 fingerprint.
-   *
-   * This method:
-   * - Opens a TLS connection to the given URL
-   * - Extracts the leaf certificate presented by the server
-   * - Computes its SHA-256 fingerprint
-   * - Compares it against the provided or configured fingerprint
+   * Applies plugin configuration.
    *
-   * NOTE:
-   * - No HTTP request body is sent
-   * - The certificate trust chain is NOT validated
-   * - Only the leaf certificate fingerprint is checked
+   * This method MUST be called exactly once from the plugin's load() method.
+   * It translates static configuration into runtime behavior
+   * (e.g. enabling verbose logging).
+   */
+  fun updateConfig(newConfig: SSLPinningConfig) {
+    this.config = newConfig
+    SSLPinningLogger.verbose = newConfig.verboseLogging
+    SSLPinningLogger.debug(
+      "Configuration applied. Verbose logging:",
+      newConfig.verboseLogging.toString(),
+    )
+  }
+
+  // ---------------------------------------------------------------------------
+  // Single fingerprint
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Validates the SSL certificate of a HTTPS endpoint
+   * using a single SHA-256 fingerprint.
    */
+  @Throws(SSLPinningError::class)
   fun checkCertificate(
     urlString: String,
     fingerprintFromArgs: String?,
-    callback: (Map<String, Any>) -> Unit,
-  ) {
+  ): Map<String, Any> {
     val fingerprint =
       fingerprintFromArgs ?: config.fingerprint
 
     if (fingerprint == null) {
-      callback(
-        mapOf(
-          "fingerprintMatched" to false,
-          "error" to "No fingerprint provided (args or config)",
-        ),
+      throw SSLPinningError.Unavailable(
+        "No fingerprint provided (args or config)",
       )
-      return
     }
 
-    performCheck(urlString, listOf(fingerprint), callback)
+    return performCheck(
+      urlString = urlString,
+      fingerprints = listOf(fingerprint),
+    )
   }
 
-  // ---- Multiple fingerprints ----
+  // ---------------------------------------------------------------------------
+  // Multiple fingerprints
+  // ---------------------------------------------------------------------------
 
   /**
-   * Validates the SSL certificate of a HTTPS endpoint using multiple allowed fingerprints.
-   *
-   * The certificate is considered valid if **any** of the provided fingerprints
-   * matches the server's leaf certificate fingerprint.
-   *
-   * This is typically used to support certificate rotation.
+   * Validates the SSL certificate of a HTTPS endpoint
+   * using multiple allowed SHA-256 fingerprints.
    */
+  @Throws(SSLPinningError::class)
   fun checkCertificates(
     urlString: String,
     fingerprintsFromArgs: List<String>?,
-    callback: (Map<String, Any>) -> Unit,
-  ) {
+  ): Map<String, Any> {
     val fingerprints =
       fingerprintsFromArgs?.takeIf { it.isNotEmpty() }
         ?: config.fingerprints.takeIf { it.isNotEmpty() }
 
     if (fingerprints == null) {
-      callback(
-        mapOf(
-          "fingerprintMatched" to false,
-          "error" to "No fingerprints provided (args or config)",
-        ),
+      throw SSLPinningError.Unavailable(
+        "No fingerprints provided (args or config)",
       )
-      return
     }
 
-    performCheck(urlString, fingerprints, callback)
+    return performCheck(
+      urlString = urlString,
+      fingerprints = fingerprints,
+    )
   }
 
-  // ---- Shared implementation ----
+  // ---------------------------------------------------------------------------
+  // Shared implementation
+  // ---------------------------------------------------------------------------
 
   /**
-   * Shared internal implementation for SSL pinning validation.
+   * Performs the actual SSL pinning validation.
+   *
+   * This method:
+   * - Validates the HTTPS URL
+   * - Opens a TLS connection
+   * - Extracts the server leaf certificate
+   * - Compares its SHA-256 fingerprint
+   *   against the expected ones
    *
-   * This method performs the actual TLS handshake and fingerprint comparison.
-   * It is intentionally isolated to avoid duplication between
-   * single and multi fingerprint modes.
+   * IMPORTANT:
+   * - The system trust chain is NOT evaluated
+   * - Only fingerprint matching determines acceptance
    */
+  @Throws(SSLPinningError::class)
   private fun performCheck(
     urlString: String,
     fingerprints: List<String>,
-    callback: (Map<String, Any>) -> Unit,
-  ) {
-    val url = SSLPinningUtils.httpsUrl(urlString)
-    if (url == null) {
-      callback(
-        mapOf(
-          "fingerprintMatched" to false,
-          "error" to "Invalid HTTPS URL",
-          "errorCode" to "UNKNOWN_TYPE",
-        ),
-      )
-      return
-    }
+  ): Map<String, Any> {
+    val url =
+      SSLPinningUtils.httpsUrl(urlString)
+        ?: throw SSLPinningError.UnknownType(
+          "Invalid HTTPS URL",
+        )
+
+    return try {
+      val certificate = getCertificate(url)
 
-    try {
-      val cert = getCertificate(url)
       val actualFingerprint =
         SSLPinningUtils.normalizeFingerprint(
-          SSLPinningUtils.sha256Fingerprint(cert),
+          SSLPinningUtils.sha256Fingerprint(certificate),
         )
 
       val normalizedExpected =
-        fingerprints.map { SSLPinningUtils.normalizeFingerprint(it) }
+        fingerprints.map {
+          SSLPinningUtils.normalizeFingerprint(it)
+        }
 
       val matchedFingerprint =
-        normalizedExpected.firstOrNull { it == actualFingerprint }
+        normalizedExpected.firstOrNull {
+          it == actualFingerprint
+        }
 
       val matched = matchedFingerprint != null
 
-      SSLPinningLogger.debug("SSLPinning matched:", matched.toString())
+      SSLPinningLogger.debug(
+        "SSLPinning matched:",
+        matched.toString(),
+      )
 
-      callback(
-        mapOf(
-          "actualFingerprint" to actualFingerprint,
-          "fingerprintMatched" to matched,
-          "matchedFingerprint" to (matchedFingerprint ?: ""),
-        ),
+      mapOf(
+        "actualFingerprint" to actualFingerprint,
+        "fingerprintMatched" to matched,
+        "matchedFingerprint" to (matchedFingerprint ?: ""),
       )
+    } catch (e: SSLPinningError) {
+      throw e
     } catch (e: Exception) {
-      SSLPinningLogger.error("Certificate check failed", e)
-      callback(
-        mapOf(
-          "fingerprintMatched" to false,
-          "error" to e.message.orEmpty(),
-          "errorCode" to "INIT_FAILED",
-        ),
+      SSLPinningLogger.error(
+        "Certificate check failed",
+        e,
+      )
+      throw SSLPinningError.InitFailed(
+        e.message ?: "SSL pinning failed",
       )
     }
   }
 
-  // ---- Certificate retrieval ----
+  // ---------------------------------------------------------------------------
+  // Certificate retrieval
+  // ---------------------------------------------------------------------------
 
   /**
-   * Opens a TLS connection and extracts the server leaf certificate.
-   *
-   * A permissive TrustManager is intentionally used to allow
-   * inspection of the certificate without enforcing trust validation.
+   * Opens a TLS connection and extracts
+   * the server leaf certificate.
    *
-   * SECURITY NOTE:
-   * This does NOT bypass SSL pinning security, because the fingerprint
-   * comparison is performed manually after extraction.
+   * A permissive TrustManager is intentionally used
+   * to allow certificate inspection without enforcing
+   * system trust validation.
    */
+  @Throws(Exception::class)
   private fun getCertificate(url: URL): Certificate {
     val trustManagers =
       arrayOf<TrustManager>(
         object : X509TrustManager {
-          override fun getAcceptedIssuers() = arrayOf<java.security.cert.X509Certificate>()
+          override fun getAcceptedIssuers() = emptyArray<java.security.cert.X509Certificate>()
 
           override fun checkClientTrusted(
             certs: Array<java.security.cert.X509Certificate>,
@@ -173,16 +208,28 @@ class SSLPinningImpl(
         },
       )
 
-    val sslContext = SSLContext.getInstance("TLS")
-    sslContext.init(null, trustManagers, java.security.SecureRandom())
+    val sslContext =
+      SSLContext.getInstance("TLS")
+
+    sslContext.init(
+      null,
+      trustManagers,
+      java.security.SecureRandom(),
+    )
+
+    val connection =
+      url.openConnection() as HttpsURLConnection
+
+    connection.sslSocketFactory =
+      sslContext.socketFactory
 
-    val connection = url.openConnection() as HttpsURLConnection
-    connection.sslSocketFactory = sslContext.socketFactory
     connection.connect()
 
-    val cert = connection.serverCertificates.first()
+    val certificate =
+      connection.serverCertificates.first()
+
     connection.disconnect()
 
-    return cert
+    return certificate
   }
 }

package/android/src/main/java/io/capkit/sslpinning/SSLPinningPlugin.kt

@@ -6,53 +6,140 @@ import com.getcapacitor.Plugin
 import com.getcapacitor.PluginCall
 import com.getcapacitor.PluginMethod
 import com.getcapacitor.annotation.CapacitorPlugin
-import io.capkit.sslpinning.utils.SSLPinningLogger
 
+/**
+ * Capacitor bridge for the SSLPinning plugin (Android).
+ *
+ * Responsibilities:
+ * - Parse JavaScript input
+ * - Call the native implementation
+ * - Resolve or reject PluginCall
+ * - Map native errors to JS-facing error codes
+ */
 @CapacitorPlugin(name = "SSLPinning")
 class SSLPinningPlugin : Plugin() {
+  // ---------------------------------------------------------------------------
+  // Properties
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Immutable plugin configuration.
+   * Parsed once during plugin initialization.
+   */
+  private lateinit var config: SSLPinningConfig
+
+  /**
+   * Native implementation containing
+   * platform-specific logic only.
+   */
   private lateinit var implementation: SSLPinningImpl
 
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Called once when the plugin is loaded by the Capacitor bridge.
+   *
+   * This is the correct place to:
+   * - read static configuration
+   * - initialize native resources
+   * - inject configuration into the implementation
+   */
   override fun load() {
-    val config = SSLPinningConfig(this)
-    SSLPinningLogger.verbose = config.verboseLogging
-    implementation = SSLPinningImpl(config)
+    super.load()
+
+    config = SSLPinningConfig(this)
+    implementation = SSLPinningImpl(context)
+    implementation.updateConfig(config)
   }
 
+  // ---------------------------------------------------------------------------
+  // Error Mapping
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Maps native SSLPinningError values
+   * to JavaScript-facing error codes.
+   */
+  private fun reject(
+    call: PluginCall,
+    error: SSLPinningError,
+  ) {
+    val code =
+      when (error) {
+        is SSLPinningError.Unavailable -> "UNAVAILABLE"
+        is SSLPinningError.PermissionDenied -> "PERMISSION_DENIED"
+        is SSLPinningError.InitFailed -> "INIT_FAILED"
+        is SSLPinningError.UnknownType -> "UNKNOWN_TYPE"
+      }
+
+    call.reject(error.message, code)
+  }
+
+  // ---------------------------------------------------------------------------
+  // SSL Pinning (single fingerprint)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Validates the SSL certificate of a HTTPS endpoint
+   * using a single fingerprint.
+   */
   @PluginMethod
   fun checkCertificate(call: PluginCall) {
-    val url = call.getString("url") ?: ""
-    val fingerprint = call.getString("fingerprint")
-
-    if (url.isEmpty()) {
-      val result = JSObject()
-      result.put("fingerprintMatched", false)
-      result.put("error", "Missing url")
-      call.resolve(result)
+    val url: String? = call.getString("url")
+    val fingerprint: String? = call.getString("fingerprint")
+
+    if (url.isNullOrBlank()) {
+      call.reject("Missing url", "UNKNOWN_TYPE")
       return
     }
 
     execute {
-      implementation.checkCertificate(url, fingerprint) { data ->
-        val result = JSObject()
-        for (entry in data.entries) {
-          result.put(entry.key, entry.value)
+      try {
+        val result: Map<String, Any> =
+          implementation.checkCertificate(
+            urlString = url,
+            fingerprintFromArgs = fingerprint,
+          )
+
+        val jsResult = JSObject()
+        for ((key, value) in result) {
+          jsResult.put(key, value)
         }
-        call.resolve(result)
+
+        call.resolve(jsResult)
+      } catch (error: SSLPinningError) {
+        reject(call, error)
+      } catch (error: Exception) {
+        call.reject(
+          error.message ?: "SSL pinning failed",
+          "INIT_FAILED",
+        )
       }
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // SSL Pinning (multiple fingerprints)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Validates the SSL certificate of a HTTPS endpoint
+   * using multiple allowed fingerprints.
+   */
   @PluginMethod
   fun checkCertificates(call: PluginCall) {
-    val url = call.getString("url") ?: ""
+    val url: String? = call.getString("url")
 
     val jsArray: JSArray? = call.getArray("fingerprints")
+
     val fingerprints: List<String>? =
       if (jsArray != null && jsArray.length() > 0) {
         val list = ArrayList<String>()
         for (i in 0 until jsArray.length()) {
           val value = jsArray.getString(i)
-          if (!value.isNullOrEmpty()) {
+          if (!value.isNullOrBlank()) {
             list.add(value)
           }
         }
@@ -61,22 +148,52 @@ class SSLPinningPlugin : Plugin() {
         null
       }
 
-    if (url.isEmpty()) {
-      val result = JSObject()
-      result.put("fingerprintMatched", false)
-      result.put("error", "Missing url")
-      call.resolve(result)
+    if (url.isNullOrBlank()) {
+      call.reject("Missing url", "UNKNOWN_TYPE")
       return
     }
 
     execute {
-      implementation.checkCertificates(url, fingerprints) { data ->
-        val result = JSObject()
-        for (entry in data.entries) {
-          result.put(entry.key, entry.value)
+      try {
+        val result: Map<String, Any> =
+          implementation.checkCertificates(
+            urlString = url,
+            fingerprintsFromArgs = fingerprints,
+          )
+
+        val jsResult = JSObject()
+        for ((key, value) in result) {
+          jsResult.put(key, value)
         }
-        call.resolve(result)
+
+        call.resolve(jsResult)
+      } catch (error: SSLPinningError) {
+        reject(call, error)
+      } catch (error: Exception) {
+        call.reject(
+          error.message ?: "SSL pinning failed",
+          "INIT_FAILED",
+        )
       }
     }
   }
+
+  // ---------------------------------------------------------------------------
+  // Version
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the native plugin version.
+   *
+   * NOTE:
+   * - This method is guaranteed not to fail
+   * - Therefore it does NOT use TestError
+   * - Version is injected at build time from package.json
+   */
+  @PluginMethod
+  fun getPluginVersion(call: PluginCall) {
+    val ret = JSObject()
+    ret.put("version", BuildConfig.PLUGIN_VERSION)
+    call.resolve(ret)
+  }
 }