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

package/android/build.gradle

@@ -0,0 +1,103 @@
+buildscript {
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+plugins {
+    id "org.jlleitschuh.gradle.ktlint" version "12.1.1" apply false
+}
+
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    androidxCoreKTXVersion = project.hasProperty('androidxCoreKTXVersion') ? rootProject.ext.androidxCoreKTXVersion : '1.17.0'
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'kotlin-parcelize'
+apply plugin: 'org.jlleitschuh.gradle.ktlint'
+
+import groovy.json.JsonSlurper
+
+def getPluginVersion() {
+    try {
+        def packageJsonFile = file('../package.json')
+        if (packageJsonFile.exists()) {
+            def packageJson = new JsonSlurper().parseText(packageJsonFile.text)
+            return packageJson.version
+        }
+    } catch (Exception e) {
+        // Ignore errors and fallback
+    }
+    return "0.0.15" // Fallback version
+}
+
+def pluginVersion = getPluginVersion()
+
+android {
+    namespace = "io.capkit.sslpinning"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion as Integer  : 36
+
+    // AGP 8.0+ disables BuildConfig by default for libraries. 
+    // We need to enable it to inject the plugin version.
+    buildFeatures {
+        buildConfig = true
+    }
+
+    defaultConfig {
+        minSdkVersion = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion as Integer  : 24
+        targetSdkVersion = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion as Integer  : 36
+        versionCode = 1
+
+        // Dynamic versioning (feature enabled)
+        versionName = pluginVersion
+
+        // Injects the version into the BuildConfig class ONLY if feature is enabled
+        buildConfigField "String", "PLUGIN_VERSION", "\"${pluginVersion}\""
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled = false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lint {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation "androidx.core:core-ktx:$androidxCoreKTXVersion"
+
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>

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

@@ -0,0 +1,22 @@
+package io.capkit.sslpinning
+
+import com.getcapacitor.Plugin
+
+class SSLPinningConfig(plugin: Plugin) {
+  val verboseLogging: Boolean
+  val fingerprint: String?
+  val fingerprints: List<String>
+
+  init {
+    val config = plugin.getConfig()
+
+    verboseLogging = config.getBoolean("verboseLogging", false)
+
+    val fp = config.getString("fingerprint")
+    fingerprint = if (fp.isNullOrBlank()) null else fp
+
+    fingerprints =
+      config.getArray("fingerprints")?.toList()?.mapNotNull { it as? String }
+        ?: emptyList()
+  }
+}

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

@@ -0,0 +1,188 @@
+package io.capkit.sslpinning
+
+import io.capkit.sslpinning.utils.SSLPinningLogger
+import io.capkit.sslpinning.utils.SSLPinningUtils
+import java.net.URL
+import java.security.cert.Certificate
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.SSLContext
+import javax.net.ssl.TrustManager
+import javax.net.ssl.X509TrustManager
+
+class SSLPinningImpl(
+  private val config: SSLPinningConfig,
+) {
+  // ---- Single fingerprint ----
+
+  /**
+   * 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
+   *
+   * NOTE:
+   * - No HTTP request body is sent
+   * - The certificate trust chain is NOT validated
+   * - Only the leaf certificate fingerprint is checked
+   */
+  fun checkCertificate(
+    urlString: String,
+    fingerprintFromArgs: String?,
+    callback: (Map<String, Any>) -> Unit,
+  ) {
+    val fingerprint =
+      fingerprintFromArgs ?: config.fingerprint
+
+    if (fingerprint == null) {
+      callback(
+        mapOf(
+          "fingerprintMatched" to false,
+          "error" to "No fingerprint provided (args or config)",
+        ),
+      )
+      return
+    }
+
+    performCheck(urlString, listOf(fingerprint), callback)
+  }
+
+  // ---- 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.
+   */
+  fun checkCertificates(
+    urlString: String,
+    fingerprintsFromArgs: List<String>?,
+    callback: (Map<String, Any>) -> Unit,
+  ) {
+    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)",
+        ),
+      )
+      return
+    }
+
+    performCheck(urlString, fingerprints, callback)
+  }
+
+  // ---- Shared implementation ----
+
+  /**
+   * Shared internal implementation for SSL pinning validation.
+   *
+   * This method performs the actual TLS handshake and fingerprint comparison.
+   * It is intentionally isolated to avoid duplication between
+   * single and multi fingerprint modes.
+   */
+  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
+    }
+
+    try {
+      val cert = getCertificate(url)
+      val actualFingerprint =
+        SSLPinningUtils.normalizeFingerprint(
+          SSLPinningUtils.sha256Fingerprint(cert),
+        )
+
+      val normalizedExpected =
+        fingerprints.map { SSLPinningUtils.normalizeFingerprint(it) }
+
+      val matchedFingerprint =
+        normalizedExpected.firstOrNull { it == actualFingerprint }
+
+      val matched = matchedFingerprint != null
+
+      SSLPinningLogger.debug("SSLPinning matched:", matched.toString())
+
+      callback(
+        mapOf(
+          "actualFingerprint" to actualFingerprint,
+          "fingerprintMatched" to matched,
+          "matchedFingerprint" to (matchedFingerprint ?: ""),
+        ),
+      )
+    } catch (e: Exception) {
+      SSLPinningLogger.error("Certificate check failed", e)
+      callback(
+        mapOf(
+          "fingerprintMatched" to false,
+          "error" to e.message.orEmpty(),
+          "errorCode" to "INIT_FAILED",
+        ),
+      )
+    }
+  }
+
+  // ---- 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.
+   *
+   * SECURITY NOTE:
+   * This does NOT bypass SSL pinning security, because the fingerprint
+   * comparison is performed manually after extraction.
+   */
+  private fun getCertificate(url: URL): Certificate {
+    val trustManagers =
+      arrayOf<TrustManager>(
+        object : X509TrustManager {
+          override fun getAcceptedIssuers() = arrayOf<java.security.cert.X509Certificate>()
+
+          override fun checkClientTrusted(
+            certs: Array<java.security.cert.X509Certificate>,
+            authType: String,
+          ) {}
+
+          override fun checkServerTrusted(
+            certs: Array<java.security.cert.X509Certificate>,
+            authType: String,
+          ) {}
+        },
+      )
+
+    val sslContext = SSLContext.getInstance("TLS")
+    sslContext.init(null, trustManagers, java.security.SecureRandom())
+
+    val connection = url.openConnection() as HttpsURLConnection
+    connection.sslSocketFactory = sslContext.socketFactory
+    connection.connect()
+
+    val cert = connection.serverCertificates.first()
+    connection.disconnect()
+
+    return cert
+  }
+}

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

@@ -0,0 +1,82 @@
+package io.capkit.sslpinning
+
+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 io.capkit.sslpinning.utils.SSLPinningLogger
+
+@CapacitorPlugin(name = "SSLPinning")
+class SSLPinningPlugin : Plugin() {
+  private lateinit var implementation: SSLPinningImpl
+
+  override fun load() {
+    val config = SSLPinningConfig(this)
+    SSLPinningLogger.verbose = config.verboseLogging
+    implementation = SSLPinningImpl(config)
+  }
+
+  @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)
+      return
+    }
+
+    execute {
+      implementation.checkCertificate(url, fingerprint) { data ->
+        val result = JSObject()
+        for (entry in data.entries) {
+          result.put(entry.key, entry.value)
+        }
+        call.resolve(result)
+      }
+    }
+  }
+
+  @PluginMethod
+  fun checkCertificates(call: PluginCall) {
+    val url = 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()) {
+            list.add(value)
+          }
+        }
+        if (list.isNotEmpty()) list else null
+      } else {
+        null
+      }
+
+    if (url.isEmpty()) {
+      val result = JSObject()
+      result.put("fingerprintMatched", false)
+      result.put("error", "Missing url")
+      call.resolve(result)
+      return
+    }
+
+    execute {
+      implementation.checkCertificates(url, fingerprints) { data ->
+        val result = JSObject()
+        for (entry in data.entries) {
+          result.put(entry.key, entry.value)
+        }
+        call.resolve(result)
+      }
+    }
+  }
+}

package/android/src/main/java/io/capkit/sslpinning/utils/SSLPinningLogger.kt

@@ -0,0 +1,85 @@
+package io.capkit.sslpinning.utils
+
+import android.util.Log
+
+/**
+ * Centralized logging utility for the SSLPinning plugin.
+ *
+ * This logging provides a single entry point for all native logs
+ * and supports runtime-controlled verbose logging.
+ *
+ * The goal is to avoid scattering `if (verbose)` checks across
+ * business logic and keep logging behavior consistent.
+ */
+object SSLPinningLogger {
+  /**
+   * Logcat tag used for all plugin logs.
+   * Helps filtering logs during debugging.
+   */
+  private const val TAG = "⚡️ SSLPinning"
+
+  /**
+   * Controls whether debug logs are printed.
+   *
+   * This flag should be set once during plugin initialization
+   * based on configuration values.
+   */
+  var verbose: Boolean = false
+
+  /**
+   * Prints a debug / verbose log message.
+   *
+   * This method should be used for development-time diagnostics
+   * and is automatically silenced when [verbose] is false.
+   *
+   * @param messages One or more message fragments to be concatenated.
+   */
+  fun debug(vararg messages: String) {
+    if (verbose) {
+      log(TAG, Log.DEBUG, *messages)
+    }
+  }
+
+  /**
+   * Prints an error log message.
+   *
+   * Error logs are always printed regardless of [verbose] state.
+   *
+   * @param message Human-readable error description.
+   * @param e Optional exception for stack trace logging.
+   */
+  fun error(
+    message: String,
+    e: Throwable? = null,
+  ) {
+    val sb = StringBuilder(message)
+    if (e != null) {
+      sb.append(" | Error: ").append(e.message)
+    }
+    Log.e(TAG, sb.toString(), e)
+  }
+
+  /**
+   * Internal low-level log dispatcher.
+   *
+   * Joins message fragments and forwards them to Android's Log API
+   * using the specified priority.
+   */
+  fun log(
+    tag: String,
+    level: Int,
+    vararg messages: String,
+  ) {
+    val sb = StringBuilder()
+    for (msg in messages) {
+      sb.append(msg).append(" ")
+    }
+    when (level) {
+      Log.DEBUG -> Log.d(tag, sb.toString())
+      Log.INFO -> Log.i(tag, sb.toString())
+      Log.WARN -> Log.w(tag, sb.toString())
+      Log.ERROR -> Log.e(tag, sb.toString())
+      else -> Log.v(tag, sb.toString())
+    }
+  }
+}

package/android/src/main/java/io/capkit/sslpinning/utils/SSLPinningUtils.kt

@@ -0,0 +1,44 @@
+package io.capkit.sslpinning.utils
+
+import java.net.URL
+import java.security.MessageDigest
+import java.security.cert.Certificate
+
+object SSLPinningUtils {
+  /**
+   * Validates that the provided string is a valid HTTPS URL.
+   *
+   * Non-HTTPS URLs are explicitly rejected to prevent insecure usage.
+   */
+  fun httpsUrl(value: String): URL? {
+    return try {
+      val url = URL(value)
+      if (url.protocol == "https") url else null
+    } catch (_: Exception) {
+      null
+    }
+  }
+
+  /**
+   * Normalizes a fingerprint string by:
+   * - Removing colon separators
+   * - Converting to lowercase
+   *
+   * This allows consistent comparison across platforms.
+   */
+  fun normalizeFingerprint(value: String): String {
+    return value.replace(":", "").lowercase()
+  }
+
+  /**
+   * Computes the SHA-256 fingerprint of an X.509 certificate.
+   *
+   * The returned format uses colon-separated hexadecimal pairs,
+   * matching common OpenSSL representations.
+   */
+  fun sha256Fingerprint(cert: Certificate): String {
+    val md = MessageDigest.getInstance("SHA-256")
+    val digest = md.digest(cert.encoded)
+    return digest.joinToString(":") { "%02x".format(it) }
+  }
+}

package/dist/cli/fingerprint.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import https from 'https';
+import { createRequire } from 'module';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+const require$1 = createRequire(import.meta.url);
+const pkg = require$1('../../package.json');
+async function getCertificate(domain, insecure) {
+    return new Promise((resolve, reject) => {
+        const options = {
+            host: domain,
+            port: 443,
+            method: 'GET',
+            rejectUnauthorized: !insecure,
+        };
+        const req = https.request(options, (res) => {
+            var _a, _b, _c;
+            const socket = res.socket;
+            const cert = (_a = socket === null || socket === void 0 ? void 0 : socket.getPeerCertificate) === null || _a === void 0 ? void 0 : _a.call(socket, true);
+            if (!(cert === null || cert === void 0 ? void 0 : cert.raw)) {
+                reject(new Error('Unable to retrieve peer certificate'));
+                return;
+            }
+            const fingerprint = crypto
+                .createHash('sha256')
+                .update(cert.raw)
+                .digest('hex')
+                .match(/.{2}/g)
+                .join(':')
+                .toUpperCase();
+            resolve({
+                domain,
+                subject: (_b = cert.subject) !== null && _b !== void 0 ? _b : {},
+                issuer: (_c = cert.issuer) !== null && _c !== void 0 ? _c : {},
+                validFrom: cert.valid_from,
+                validTo: cert.valid_to,
+                fingerprint,
+            });
+        });
+        req.on('error', reject);
+        req.end();
+    });
+}
+function formatOutput(results, mode, format) {
+    const fingerprints = results.map((r) => r.fingerprint);
+    switch (format) {
+        case 'fingerprints':
+            return `export const fingerprints = ${JSON.stringify(fingerprints, null, 2)};`;
+        case 'capacitor': {
+            if (mode === 'single') {
+                return `plugins: {
+  SSLPinning: {
+    fingerprint: "${fingerprints[0]}"
+  }
+}`;
+            }
+            return `plugins: {
+  SSLPinning: {
+    fingerprints: ${JSON.stringify(fingerprints, null, 4)}
+  }
+}`;
+        }
+        case 'capacitor-plugin': {
+            if (mode === 'single') {
+                return `SSLPinning: {
+  fingerprint: "${fingerprints[0]}"
+}`;
+            }
+            return `SSLPinning: {
+  fingerprints: ${JSON.stringify(fingerprints, null, 4)}
+}`;
+        }
+        case 'capacitor-json': {
+            if (mode === 'single') {
+                return JSON.stringify({
+                    plugins: {
+                        SSLPinning: {
+                            fingerprint: fingerprints[0],
+                        },
+                    },
+                }, null, 2);
+            }
+            return JSON.stringify({
+                plugins: {
+                    SSLPinning: {
+                        fingerprints,
+                    },
+                },
+            }, null, 2);
+        }
+        case 'json':
+        default:
+            return JSON.stringify(results, null, 2);
+    }
+}
+async function main() {
+    var _a, _b, _c;
+    const argv = await yargs(hideBin(process.argv))
+        .usage('Usage: $0 <domains...> [options]')
+        .version(pkg.version)
+        .option('out', {
+        alias: 'o',
+        type: 'string',
+        description: 'Output file path',
+    })
+        .option('format', {
+        alias: 'f',
+        type: 'string',
+        choices: ['json', 'fingerprints', 'capacitor', 'capacitor-plugin', 'capacitor-json'],
+        default: 'json',
+        description: 'Output format',
+    })
+        .option('mode', {
+        type: 'string',
+        choices: ['single', 'multi'],
+        default: 'single',
+        description: 'Fingerprint mode (single or multi)',
+    })
+        .option('insecure', {
+        type: 'boolean',
+        default: true,
+        description: 'Allow insecure TLS connections (disables certificate validation)',
+    })
+        .demandCommand(1, 'At least one domain is required')
+        .help().argv;
+    const domains = argv._;
+    const results = [];
+    console.log('Fetching certificates...\n');
+    for (const domain of domains) {
+        try {
+            const certInfo = await getCertificate(domain, argv.insecure);
+            results.push(certInfo);
+            console.log(`Domain: ${certInfo.domain}`);
+            console.log(`Subject: ${(_a = certInfo.subject.CN) !== null && _a !== void 0 ? _a : '-'}`);
+            console.log(`Issuer: ${(_b = certInfo.issuer.CN) !== null && _b !== void 0 ? _b : '-'}`);
+            console.log(`Valid From: ${certInfo.validFrom}`);
+            console.log(`Valid To: ${certInfo.validTo}`);
+            console.log(`SHA256 Fingerprint: ${certInfo.fingerprint}`);
+            console.log('-------------------\n');
+        }
+        catch (err) {
+            console.error(`Error fetching cert for ${domain}: ${(_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : err}`);
+            console.log('-------------------\n');
+        }
+    }
+    const output = formatOutput(results, argv.mode, argv.format);
+    if (argv.out) {
+        await fs.writeFile(argv.out, output);
+        console.log(`Results written to ${argv.out}`);
+    }
+    else {
+        console.log(output);
+    }
+    process.exit(0);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=fingerprint.js.map