@cap-kit/tls-fingerprint 8.0.0

package/android/src/main/java/io/capkit/settings/TLSFingerprintImpl.kt

@@ -0,0 +1,333 @@
+package io.capkit.tlsfingerprint
+
+import android.content.Context
+import io.capkit.tlsfingerprint.config.TLSFingerprintConfig
+import io.capkit.tlsfingerprint.error.TLSFingerprintError
+import io.capkit.tlsfingerprint.error.TLSFingerprintErrorMessages
+import io.capkit.tlsfingerprint.logger.TLSFingerprintLogger
+import io.capkit.tlsfingerprint.model.TLSFingerprintResultModel
+import io.capkit.tlsfingerprint.utils.TLSFingerprintUtils
+import java.io.IOException
+import java.net.SocketTimeoutException
+import java.net.URL
+import java.security.cert.Certificate
+import java.security.cert.X509Certificate
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.SSLContext
+import javax.net.ssl.TrustManager
+import javax.net.ssl.X509TrustManager
+
+/**
+ * Native Android implementation for the TLSFingerprint plugin.
+ *
+ * Responsibilities:
+ * - Perform platform-specific SSL pinning logic
+ * - Interact with system networking APIs
+ * - Throw typed TLSFingerprintError values on failure
+ *
+ * Forbidden:
+ * - Accessing PluginCall
+ * - Referencing Capacitor APIs
+ * - Constructing JavaScript payloads
+ */
+class TLSFingerprintImpl(
+  private val context: Context,
+) {
+  // -----------------------------------------------------------------------------
+  // Constants
+  // -----------------------------------------------------------------------------
+
+  companion object {
+    private const val TIMEOUT_MS = 10_000
+  }
+
+  // -----------------------------------------------------------------------------
+  // Properties
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Cached plugin configuration.
+   * Injected once during plugin initialization.
+   */
+  private lateinit var config: TLSFingerprintConfig
+
+  // -----------------------------------------------------------------------------
+  // Configuration
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Applies plugin configuration.
+   *
+   * 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: TLSFingerprintConfig) {
+    this.config = newConfig
+    TLSFingerprintLogger.verbose = newConfig.verboseLogging
+
+    TLSFingerprintLogger.debug(
+      "Configuration applied. Verbose logging:",
+      newConfig.verboseLogging.toString(),
+    )
+  }
+
+  // -----------------------------------------------------------------------------
+  // Single fingerprint
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Validates the SSL certificate of a HTTPS endpoint
+   * using a single SHA-256 fingerprint.
+   *
+   * Resolution order:
+   * 1. Runtime fingerprint argument
+   * 2. Static configuration fingerprint
+   *
+   * @throws TLSFingerprintError.Unavailable if no fingerprint available.
+   */
+  @Throws(TLSFingerprintError::class)
+  fun checkCertificate(
+    urlString: String,
+    fingerprintFromArgs: String?,
+  ): TLSFingerprintResultModel {
+    val fingerprint =
+      fingerprintFromArgs ?: config.fingerprint
+
+    if (fingerprint != null) {
+      return performCheck(
+        urlString = urlString,
+        fingerprints = listOf(fingerprint),
+      )
+    }
+
+    throw TLSFingerprintError.Unavailable(
+      TLSFingerprintErrorMessages.NO_FINGERPRINTS_PROVIDED,
+    )
+  }
+
+  // -----------------------------------------------------------------------------
+  // Multiple fingerprints
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Validates the SSL certificate of a HTTPS endpoint
+   * using multiple allowed SHA-256 fingerprints.
+   *
+   * A match is considered valid if ANY provided fingerprint matches.
+   *
+   * @throws TLSFingerprintError.Unavailable if no fingerprints available.
+   */
+  @Throws(TLSFingerprintError::class)
+  fun checkCertificates(
+    urlString: String,
+    fingerprintsFromArgs: List<String>?,
+  ): TLSFingerprintResultModel {
+    val fingerprints =
+      fingerprintsFromArgs?.takeIf { it.isNotEmpty() }
+        ?: config.fingerprints.takeIf { it.isNotEmpty() }
+
+    if (fingerprints != null) {
+      return performCheck(
+        urlString = urlString,
+        fingerprints = fingerprints,
+      )
+    }
+
+    throw TLSFingerprintError.Unavailable(
+      TLSFingerprintErrorMessages.NO_FINGERPRINTS_PROVIDED,
+    )
+  }
+
+  // -----------------------------------------------------------------------------
+  // Shared implementation
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Determines and executes the SSL fingerprint validation for the given request.
+   *
+   * Evaluation order:
+   *
+   * 1. Excluded domain → bypass validation entirely.
+   * 2. Fingerprint-based validation.
+   *
+   * @throws TLSFingerprintError when validation fails.
+   */
+  @Throws(TLSFingerprintError::class)
+  private fun performCheck(
+    urlString: String,
+    fingerprints: List<String>,
+  ): TLSFingerprintResultModel {
+    val url =
+      TLSFingerprintUtils.httpsUrl(urlString)
+        ?: throw TLSFingerprintError.UnknownType(
+          TLSFingerprintErrorMessages.INVALID_URL_MUST_BE_HTTPS,
+        )
+
+    val host = url.host
+
+    // -----------------------------------------------------------------------------
+    // EXCLUDED DOMAIN MODE
+    // -----------------------------------------------------------------------------
+
+    /**
+     * If the request host matches an excluded domain,
+     * fingerprint validation is bypassed.
+     * The connection uses a permissive TrustManager.
+     * System trust chain is NOT explicitly evaluated.
+     *
+     * Matching rules:
+     * - Exact match
+     * - Subdomain match
+     */
+    if (config.excludedDomains.any { excluded ->
+        val excludedLower = excluded.lowercase().trim()
+        val hostLower = host.lowercase().trim()
+        // Match exact domain or any subdomain (e.g., api.example.com matches example.com)
+        hostLower == excludedLower || hostLower.endsWith(".$excludedLower")
+      }
+    ) {
+      TLSFingerprintLogger.debug("TLSFingerprint excluded domain:", host)
+
+      try {
+        val certificate = getCertificate(url)
+        val actualFingerprint =
+          TLSFingerprintUtils.normalizeFingerprint(
+            TLSFingerprintUtils.sha256Fingerprint(certificate),
+          )
+
+        return TLSFingerprintResultModel(
+          actualFingerprint = actualFingerprint,
+          fingerprintMatched = true,
+          excludedDomain = true,
+          mode = "excluded",
+          errorCode = "EXCLUDED_DOMAIN",
+          error = TLSFingerprintErrorMessages.EXCLUDED_DOMAIN,
+        )
+      } catch (e: SocketTimeoutException) {
+        throw TLSFingerprintError.Timeout(TLSFingerprintErrorMessages.TIMEOUT)
+      } catch (e: IOException) {
+        throw TLSFingerprintError.NetworkError(TLSFingerprintErrorMessages.NETWORK_ERROR)
+      }
+    }
+
+    // -----------------------------------------------------------------------------
+    // FINGERPRINT MODE
+    // -----------------------------------------------------------------------------
+
+    /**
+     * Fingerprint-based pinning.
+     *
+     * Only the leaf certificate fingerprint is compared.
+     * The system trust chain is NOT evaluated in this mode.
+     */
+    val certificate: Certificate
+    try {
+      certificate = getCertificate(url)
+    } catch (e: SocketTimeoutException) {
+      throw TLSFingerprintError.Timeout(TLSFingerprintErrorMessages.TIMEOUT)
+    } catch (e: IOException) {
+      throw TLSFingerprintError.NetworkError(TLSFingerprintErrorMessages.NETWORK_ERROR)
+    }
+
+    val actualFingerprint =
+      TLSFingerprintUtils.normalizeFingerprint(
+        TLSFingerprintUtils.sha256Fingerprint(certificate),
+      )
+
+    val normalizedExpected =
+      fingerprints.map {
+        TLSFingerprintUtils.normalizeFingerprint(it)
+      }
+
+    val matchedFingerprint =
+      normalizedExpected.firstOrNull {
+        it == actualFingerprint
+      }
+
+    val matched = matchedFingerprint != null
+
+    val errorCode = if (matched) "" else "PINNING_FAILED"
+    val errorMessage = if (matched) "" else TLSFingerprintErrorMessages.PINNING_FAILED
+
+    TLSFingerprintLogger.debug(
+      "TLSFingerprint matched:",
+      matched.toString(),
+    )
+
+    return TLSFingerprintResultModel(
+      actualFingerprint = actualFingerprint,
+      fingerprintMatched = matched,
+      matchedFingerprint = matchedFingerprint,
+      mode = "fingerprint",
+      errorCode = errorCode,
+      error = errorMessage,
+    )
+  }
+
+  // -----------------------------------------------------------------------------
+  // Certificate retrieval
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Opens a TLS connection and extracts
+   * the server leaf certificate.
+   *
+   * SECURITY MODEL:
+   * - A permissive TrustManager is used intentionally.
+   * - The system trust chain is NOT validated.
+   * - Validation is performed manually via fingerprint comparison.
+   */
+  @Throws(Exception::class)
+  private fun getCertificate(url: URL): Certificate {
+    val trustManagers =
+      arrayOf<TrustManager>(
+        object : X509TrustManager {
+          override fun getAcceptedIssuers() = emptyArray<X509Certificate>()
+
+          override fun checkClientTrusted(
+            certs: Array<X509Certificate>,
+            authType: String,
+          ) {}
+
+          override fun checkServerTrusted(
+            certs: Array<X509Certificate>,
+            authType: String,
+          ) {}
+        },
+      )
+
+    val sslContext =
+      SSLContext.getInstance("TLS")
+
+    sslContext.init(
+      null,
+      trustManagers,
+      java.security.SecureRandom(),
+    )
+
+    val connection =
+      url.openConnection() as HttpsURLConnection
+
+    try {
+      connection.sslSocketFactory =
+        sslContext.socketFactory
+
+      connection.connectTimeout = TIMEOUT_MS
+      connection.readTimeout = TIMEOUT_MS
+
+      connection.connect()
+
+      val certificate =
+        connection.serverCertificates.first()
+
+      return certificate
+    } finally {
+      try {
+        connection.disconnect()
+      } catch (_: Exception) {
+        // Ignore disconnect errors
+      }
+    }
+  }
+}

package/android/src/main/java/io/capkit/settings/TLSFingerprintPlugin.kt

@@ -0,0 +1,342 @@
+package io.capkit.tlsfingerprint
+
+import com.getcapacitor.JSArray
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.getcapacitor.annotation.Permission
+import io.capkit.tlsfingerprint.config.TLSFingerprintConfig
+import io.capkit.tlsfingerprint.error.TLSFingerprintError
+import io.capkit.tlsfingerprint.error.TLSFingerprintErrorMessages
+import io.capkit.tlsfingerprint.logger.TLSFingerprintLogger
+import io.capkit.tlsfingerprint.model.TLSFingerprintResultModel
+import io.capkit.tlsfingerprint.utils.TLSFingerprintUtils
+import java.net.UnknownHostException
+import javax.net.ssl.SSLException
+
+/**
+ * Capacitor bridge for the TLSFingerprint plugin (Android).
+ *
+ * Responsibilities:
+ * - Parse JavaScript input
+ * - Call the native implementation
+ * - Resolve or reject PluginCall
+ * - Map native errors to JS-facing error codes
+ */
+@CapacitorPlugin(
+  name = "TLSFingerprint",
+  permissions = [
+    Permission(
+      alias = "network",
+      strings = [android.Manifest.permission.INTERNET],
+    ),
+  ],
+)
+class TLSFingerprintPlugin : Plugin() {
+  // -----------------------------------------------------------------------------
+  // Properties
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Immutable plugin configuration read from capacitor.config.ts.
+   * * CONTRACT:
+   * - Initialized exactly once in `load()`.
+   * - Treated as read-only afterwards.
+   */
+  private lateinit var config: TLSFingerprintConfig
+
+  /**
+   * Native implementation layer containing core Android logic.
+   *
+   * CONTRACT:
+   * - Owned by the Plugin layer.
+   * - MUST NOT access PluginCall or Capacitor bridge APIs directly.
+   */
+  private lateinit var implementation: TLSFingerprintImpl
+
+  // -----------------------------------------------------------------------------
+  // Companion Object
+  // -----------------------------------------------------------------------------
+
+  private companion object {
+    /**
+     * Account type identifier for internal plugin identification.
+     */
+    const val ACCOUNT_TYPE = "io.capkit.tlsfingerprint"
+
+    /**
+     * Human-readable account name for the plugin.
+     */
+    const val ACCOUNT_NAME = "TLSFingerprint"
+  }
+
+  // -----------------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Called once when the plugin is loaded by the Capacitor bridge.
+   *
+   * This method initializes the configuration container and the native
+   * implementation layer, ensuring all dependencies are injected.
+   */
+  override fun load() {
+    super.load()
+
+    config = TLSFingerprintConfig(this)
+    implementation = TLSFingerprintImpl(context)
+    implementation.updateConfig(config)
+
+    TLSFingerprintLogger.debug("Plugin loaded. Version: ", BuildConfig.PLUGIN_VERSION)
+  }
+
+  // -----------------------------------------------------------------------------
+  // Error Mapping
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Rejects the call with a message and a standardized error code.
+   * Ensure consistency with the JS TLSFingerprintErrorCode enum.
+   */
+  private fun reject(
+    call: PluginCall,
+    error: TLSFingerprintError,
+  ) {
+    val code =
+      when (error) {
+        is TLSFingerprintError.Unavailable -> "UNAVAILABLE"
+        is TLSFingerprintError.Cancelled -> "CANCELLED"
+        is TLSFingerprintError.PermissionDenied -> "PERMISSION_DENIED"
+        is TLSFingerprintError.InitFailed -> "INIT_FAILED"
+        is TLSFingerprintError.InvalidInput -> "INVALID_INPUT"
+        is TLSFingerprintError.UnknownType -> "UNKNOWN_TYPE"
+        is TLSFingerprintError.NotFound -> "NOT_FOUND"
+        is TLSFingerprintError.Conflict -> "CONFLICT"
+        is TLSFingerprintError.Timeout -> "TIMEOUT"
+        is TLSFingerprintError.NetworkError -> "NETWORK_ERROR"
+        is TLSFingerprintError.InvalidConfig -> "INVALID_INPUT"
+        is TLSFingerprintError.SslError -> "SSL_ERROR"
+      }
+
+    // Always use the message from the TLSFingerprintError instance
+    val message = error.message ?: "Unknown native error"
+    call.reject(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: String? = call.getString("url")
+    val fingerprint: String? = call.getString("fingerprint")
+
+    if (url.isNullOrBlank()) {
+      call.reject(TLSFingerprintErrorMessages.URL_REQUIRED, "INVALID_INPUT")
+      return
+    }
+
+    val parsedUrl =
+      try {
+        java.net.URL(url)
+      } catch (e: java.net.MalformedURLException) {
+        call.reject(TLSFingerprintErrorMessages.INVALID_URL, "INVALID_INPUT")
+        return
+      }
+
+    if (parsedUrl.host.isNullOrBlank()) {
+      call.reject(TLSFingerprintErrorMessages.NO_HOST_FOUND_IN_URL, "INVALID_INPUT")
+      return
+    }
+
+    if (fingerprint != null && !TLSFingerprintUtils.isValidFingerprintFormat(fingerprint)) {
+      call.reject(TLSFingerprintErrorMessages.INVALID_FINGERPRINT_FORMAT, "INVALID_INPUT")
+      return
+    }
+
+    try {
+      execute {
+        try {
+          val result: TLSFingerprintResultModel =
+            implementation.checkCertificate(
+              urlString = url ?: "",
+              fingerprintFromArgs = fingerprint,
+            )
+
+          val jsResult = JSObject()
+          jsResult.put("actualFingerprint", result.actualFingerprint)
+          jsResult.put("fingerprintMatched", result.fingerprintMatched)
+          jsResult.put("matchedFingerprint", result.matchedFingerprint)
+          jsResult.put("excludedDomain", result.excludedDomain)
+          jsResult.put("mode", result.mode)
+          jsResult.put("error", result.error)
+          jsResult.put("errorCode", result.errorCode)
+
+          call.resolve(jsResult)
+        } catch (error: TLSFingerprintError) {
+          reject(call, error)
+        } catch (error: IllegalArgumentException) {
+          call.reject(
+            error.message ?: "Invalid input",
+            "INVALID_INPUT",
+          )
+        } catch (error: SSLException) {
+          reject(call, TLSFingerprintError.SslError(error.message ?: "SSL/TLS error"))
+        } catch (error: UnknownHostException) {
+          call.reject(
+            error.message ?: "Unknown host",
+            "NETWORK_ERROR",
+          )
+        } catch (error: Exception) {
+          call.reject(
+            error.message ?: TLSFingerprintErrorMessages.INTERNAL_ERROR,
+            "INIT_FAILED",
+          )
+        }
+      }
+    } catch (error: IllegalArgumentException) {
+      call.reject(
+        error.message ?: "Invalid input",
+        "INVALID_INPUT",
+      )
+    } catch (error: Exception) {
+      call.reject(
+        error.message ?: TLSFingerprintErrorMessages.INTERNAL_ERROR,
+        "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: String? = call.getString("url")
+
+    val jsArray: JSArray? = call.getArray("fingerprints")
+
+    // Parsing JSArray to a clean Kotlin List
+    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.isNullOrBlank()) {
+            list.add(value)
+          }
+        }
+        if (list.isNotEmpty()) list else null
+      } else {
+        null
+      }
+
+    if (url.isNullOrBlank()) {
+      call.reject(TLSFingerprintErrorMessages.URL_REQUIRED, "INVALID_INPUT")
+      return
+    }
+
+    val parsedUrl =
+      try {
+        java.net.URL(url)
+      } catch (e: java.net.MalformedURLException) {
+        call.reject(TLSFingerprintErrorMessages.INVALID_URL, "INVALID_INPUT")
+        return
+      }
+
+    if (parsedUrl.host.isNullOrBlank()) {
+      call.reject(TLSFingerprintErrorMessages.NO_HOST_FOUND_IN_URL, "INVALID_INPUT")
+      return
+    }
+
+    fingerprints?.forEach { fp ->
+      if (!TLSFingerprintUtils.isValidFingerprintFormat(fp)) {
+        call.reject(TLSFingerprintErrorMessages.INVALID_FINGERPRINT_FORMAT, "INVALID_INPUT")
+        return
+      }
+    }
+
+    try {
+      execute {
+        try {
+          val result: TLSFingerprintResultModel =
+            implementation.checkCertificates(
+              urlString = url ?: "",
+              fingerprintsFromArgs = fingerprints,
+            )
+
+          val jsResult = JSObject()
+          jsResult.put("actualFingerprint", result.actualFingerprint)
+          jsResult.put("fingerprintMatched", result.fingerprintMatched)
+          jsResult.put("matchedFingerprint", result.matchedFingerprint)
+          jsResult.put("excludedDomain", result.excludedDomain)
+          jsResult.put("mode", result.mode)
+          jsResult.put("error", result.error)
+          jsResult.put("errorCode", result.errorCode)
+
+          call.resolve(jsResult)
+        } catch (error: TLSFingerprintError) {
+          reject(call, error)
+        } catch (error: IllegalArgumentException) {
+          call.reject(
+            error.message ?: "Invalid input",
+            "INVALID_INPUT",
+          )
+        } catch (error: SSLException) {
+          reject(call, TLSFingerprintError.SslError(error.message ?: "SSL/TLS error"))
+        } catch (error: UnknownHostException) {
+          call.reject(
+            error.message ?: "Unknown host",
+            "NETWORK_ERROR",
+          )
+        } catch (error: Exception) {
+          call.reject(
+            error.message ?: TLSFingerprintErrorMessages.INTERNAL_ERROR,
+            "INIT_FAILED",
+          )
+        }
+      }
+    } catch (error: IllegalArgumentException) {
+      call.reject(
+        error.message ?: "Invalid input",
+        "INVALID_INPUT",
+      )
+    } catch (error: Exception) {
+      call.reject(
+        error.message ?: TLSFingerprintErrorMessages.INTERNAL_ERROR,
+        "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)
+  }
+}