@cap-kit/tls-fingerprint 8.0.0

package/ios/Sources/TLSFingerprintPlugin/TLSFingerprintPlugin.swift

@@ -0,0 +1,219 @@
+import Foundation
+import Capacitor
+
+/**
+ Capacitor bridge for the TLSFingerprint plugin.
+
+ Responsibilities:
+ - Parse JS input
+ - Delegate to TLSFingerprintImpl
+ - Resolve or reject CAPPluginCall
+ */
+@objc(TLSFingerprintPlugin)
+public final class TLSFingerprintPlugin: CAPPlugin, CAPBridgedPlugin {
+
+    // MARK: - Plugin metadata
+
+    /// The unique identifier for the plugin.
+    public let identifier = "TLSFingerprintPlugin"
+
+    /// The name used to reference this plugin in JavaScript.
+    public let jsName = "TLSFingerprint"
+
+    /**
+     * A list of methods exposed by this plugin. These methods can be called from the JavaScript side.
+     * - `checkCertificate`: Validates an SSL certificate for a given URL.
+     * - `checkCertificates`: Validates multiple SSL certificates for given URLs.
+     * - `getPluginVersion`: Retrieves the current version of the plugin.
+     */
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "checkCertificate", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "checkCertificates", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getPluginVersion", returnType: CAPPluginReturnPromise)
+    ]
+
+    // MARK: - Properties
+
+    /// Native implementation containing platform-specific logic.
+    private let implementation = TLSFingerprintImpl()
+
+    /// Configuration instance
+    private var config: TLSFingerprintConfig?
+
+    // MARK: - Lifecycle
+
+    /**
+     Plugin lifecycle entry point.
+
+     Called once when the plugin is loaded by the Capacitor bridge.
+     This is the correct place to:
+     - read configuration values
+     - initialize native resources
+     - configure the implementation instance
+     */
+    override public func load() {
+        // Initialize TLSFingerprintConfig with the correct type
+        let cfg = TLSFingerprintConfig(plugin: self)
+        self.config = cfg
+        implementation.applyConfig(cfg)
+
+        // Log if verbose logging is enabled
+        TLSFingerprintLogger.debug("Plugin loaded. Version: ", PluginVersion.number)
+    }
+
+    // MARK: - Error Mapping
+
+    /**
+     * Rejects the call using standardized error codes from the native TLSFingerprintError enum.
+     */
+    private func reject(
+        _ call: CAPPluginCall,
+        error: TLSFingerprintError
+    ) {
+        // Use the centralized errorCode and message defined in TLSFingerprintError.swift
+        call.reject(error.message, error.errorCode)
+    }
+
+    private func handleError(_ call: CAPPluginCall, _ error: Error) {
+        if let settingsError = error as? TLSFingerprintError {
+            call.reject(settingsError.message, settingsError.errorCode)
+        } else {
+            reject(call, error: .initFailed(error.localizedDescription))
+        }
+    }
+
+    // MARK: - SSL Pinning (single fingerprint)
+
+    /**
+     Validates the SSL certificate of a HTTPS endpoint
+     using a single fingerprint.
+     */
+    @objc func checkCertificate(_ call: CAPPluginCall) {
+        let url = call.getString("url", "")
+        let fingerprintValue = call.getString("fingerprint")
+        let fingerprint =
+            fingerprintValue?.isEmpty == false
+            ? fingerprintValue
+            : nil
+
+        guard !url.isEmpty else {
+            call.reject(
+                TLSFingerprintErrorMessages.urlRequired,
+                "INVALID_INPUT"
+            )
+            return
+        }
+
+        guard let urlObj = URL(string: url), let host = urlObj.host, !host.isEmpty else {
+            call.reject(
+                TLSFingerprintErrorMessages.noHostFoundInUrl,
+                "INVALID_INPUT"
+            )
+            return
+        }
+
+        if let fp = fingerprint, !TLSFingerprintUtils.isValidFingerprintFormat(fp) {
+            call.reject(
+                TLSFingerprintErrorMessages.invalidFingerprintFormat,
+                "INVALID_INPUT"
+            )
+            return
+        }
+
+        Task {
+            do {
+                let result =
+                    try await implementation.checkCertificate(
+                        urlString: url,
+                        fingerprintFromArgs: fingerprint
+                    )
+
+                // Converting Swift TLSFingerprintResult to JSObject
+                call.resolve(result.toDictionary())
+            } catch let error as TLSFingerprintError {
+                self.reject(call, error: error)
+            } catch {
+                call.reject(
+                    error.localizedDescription,
+                    "INIT_FAILED"
+                )
+            }
+        }
+    }
+
+    // MARK: - SSL Pinning (multiple fingerprints)
+
+    /**
+     Validates the SSL certificate of a HTTPS endpoint
+     using multiple allowed fingerprints.
+     */
+    @objc func checkCertificates(_ call: CAPPluginCall) {
+        let url = call.getString("url", "")
+
+        // Extraction and filtering of optional fingerprints
+        let fingerprints =
+            call.getArray("fingerprints")?
+            .compactMap { $0 as? String }
+            .filter { !$0.isEmpty }
+
+        guard !url.isEmpty else {
+            call.reject(
+                TLSFingerprintErrorMessages.urlRequired,
+                "INVALID_INPUT"
+            )
+            return
+        }
+
+        guard let urlObj = URL(string: url), let host = urlObj.host, !host.isEmpty else {
+            call.reject(
+                TLSFingerprintErrorMessages.noHostFoundInUrl,
+                "INVALID_INPUT"
+            )
+            return
+        }
+
+        if let fps = fingerprints {
+            for fp in fps {
+                if !TLSFingerprintUtils.isValidFingerprintFormat(fp) {
+                    call.reject(
+                        TLSFingerprintErrorMessages.invalidFingerprintFormat,
+                        "INVALID_INPUT"
+                    )
+                    return
+                }
+            }
+        }
+
+        Task {
+            do {
+                let result =
+                    try await implementation.checkCertificates(
+                        urlString: url,
+                        fingerprintsFromArgs:
+                            fingerprints?.isEmpty == false
+                            ? fingerprints
+                            : nil
+                    )
+
+                call.resolve(result.toDictionary())
+            } catch let error as TLSFingerprintError {
+                self.reject(call, error: error)
+            } catch {
+                call.reject(
+                    error.localizedDescription,
+                    "INIT_FAILED"
+                )
+            }
+        }
+    }
+
+    // MARK: - Version
+
+    /// Retrieves the plugin version synchronized from package.json.
+    @objc func getPluginVersion(_ call: CAPPluginCall) {
+        // Standardized enum name across all CapKit plugins
+        call.resolve([
+            "version": PluginVersion.number
+        ])
+    }
+}

package/ios/Sources/TLSFingerprintPlugin/Version.swift

@@ -0,0 +1,16 @@
+// This file is automatically generated. Do not modify manually.
+import Foundation
+
+/**
+  Container for the plugin's version information.
+  This enum provides a centralized, single source of truth for the native 
+  version string, synchronized directly from the project's 'package.json'.
+  It ensures parity across JavaScript, Android, and iOS platforms.
+ */
+public enum PluginVersion {
+    /**
+      The semantic version string of the plugin.
+      Value synchronized from package.json: "8.0.0"
+     */
+    public static let number = "8.0.0"
+}

package/ios/Sources/TLSFingerprintPlugin/config/TLSFingerprintConfig.swift

@@ -0,0 +1,114 @@
+import Foundation
+import Capacitor
+
+/**
+ Plugin configuration container.
+
+ This struct is responsible for reading and exposing
+ static configuration values defined under the
+ `TLSFingerprint` key in capacitor.config.ts.
+
+ Configuration rules:
+ - Read once during plugin initialization
+ - Treated as immutable runtime input
+ - Accessible only from native code
+ */
+public struct TLSFingerprintConfig {
+
+    // MARK: - Configuration Keys
+
+    /**
+     Centralized definition of configuration keys.
+     Avoids string duplication and typos.
+     */
+    private enum Keys {
+        static let verboseLogging = "verboseLogging"
+        static let fingerprint = "fingerprint"
+        static let fingerprints = "fingerprints"
+        static let excludedDomains = "excludedDomains"
+    }
+
+    // MARK: - Public Configuration Values
+
+    /**
+     Enables verbose native logging.
+
+     When enabled, the plugin prints additional
+     debug information to the Xcode console.
+
+     Default: false
+     */
+    public let verboseLogging: Bool
+
+    /**
+     Default SHA-256 fingerprint used by `checkCertificate()`
+     when no fingerprint is provided at runtime.
+     */
+    public let fingerprint: String?
+
+    /**
+     Default SHA-256 fingerprints used by `checkCertificates()`
+     when no fingerprints are provided at runtime.
+     */
+    public let fingerprints: [String]
+
+    /**
+     Domains or URL prefixes excluded from SSL pinning.
+
+     Any request whose host matches one of these values
+     MUST bypass SSL pinning checks.
+     */
+    public let excludedDomains: [String]
+
+    // MARK: - Defaults
+
+    private static let defaultVerboseLogging: Bool = false
+    private static let defaultFingerprint: String? = nil
+    private static let defaultFingerprints: [String] = []
+    private static let defaultExcludedDomains: [String] = []
+
+    // MARK: - Initialization
+
+    /**
+     Initializes the configuration by reading values
+     from the Capacitor PluginConfig.
+
+     - Parameter plugin: The CAPPlugin instance used
+     to access typed configuration values.
+     */
+    init(plugin: CAPPlugin) {
+        let config = plugin.getConfig()
+
+        // Verbose logging flag
+        self.verboseLogging =
+            config.getBoolean(
+                Keys.verboseLogging,
+                Self.defaultVerboseLogging
+            )
+
+        // Synchronize logger state
+        TLSFingerprintLogger.verbose = self.verboseLogging
+
+        // Single fingerprint (optional)
+        if let value = config.getString(Keys.fingerprint),
+           !value.isEmpty {
+            self.fingerprint = value
+        } else {
+            self.fingerprint = Self.defaultFingerprint
+        }
+
+        // Multiple fingerprints (optional)
+        self.fingerprints =
+            config.getArray(Keys.fingerprints)?
+            .compactMap { $0 as? String }
+            .filter { !$0.isEmpty }
+            ?? Self.defaultFingerprints
+
+        // Excluded domains (optional)
+        self.excludedDomains =
+            config.getArray(Keys.excludedDomains)?
+            .compactMap { $0 as? String }
+            .filter { !$0.isEmpty }
+            ?? Self.defaultExcludedDomains
+    }
+}

package/ios/Sources/TLSFingerprintPlugin/error/TLSFingerprintError.swift

@@ -0,0 +1,107 @@
+import Foundation
+
+/**
+ Native error model for the TLSFingerprint plugin (iOS).
+
+ This enum represents all error categories that can be
+ produced by the native implementation layer.
+
+ Architectural rules:
+ - Must NOT reference Capacitor
+ - Must NOT reference JavaScript
+ - Must be throwable from the Impl layer
+ - Mapping to JS-facing error codes happens ONLY in the Plugin layer
+ */
+enum TLSFingerprintError: Error {
+
+    /// Feature or capability is not available on this device or configuration
+    case unavailable(String)
+
+    /// The user cancelled an interactive flow
+    case cancelled(String)
+
+    /// Required permission was denied or not granted
+    case permissionDenied(String)
+
+    /// Plugin failed to initialize or perform a required operation
+    case initFailed(String)
+
+    /// The input provided to the plugin method is invalid or malformed
+    case invalidInput(String)
+
+    /// Invalid or unsupported input was provided
+    case unknownType(String)
+
+    /// The requested resource does not exist
+    case notFound(String)
+
+    /// The operation conflicts with the current state
+    case conflict(String)
+
+    /// The operation did not complete within the expected time
+    case timeout(String)
+
+    /// The certificate fingerprint did not match any expected fingerprint
+    case pinningFailed(String)
+
+    /// SSL/TLS specific error (certificate expired, handshake failure, etc.)
+    case sslError(String)
+
+    /// Invalid or malformed configuration
+    case invalidConfig(String)
+
+    // MARK: - Human-readable message
+
+    /**
+     Human-readable error message.
+
+     This message is intended to be passed verbatim
+     to JavaScript via `call.reject(message, code)`.
+     */
+    var message: String {
+        switch self {
+        case .unavailable(let message):
+            return message
+        case .cancelled(let message):
+            return message
+        case .permissionDenied(let message):
+            return message
+        case .initFailed(let message):
+            return message
+        case .invalidInput(let message):
+            return message
+        case .unknownType(let message):
+            return message
+        case .notFound(let message):
+            return message
+        case .conflict(let message):
+            return message
+        case .timeout(let message):
+            return message
+        case .pinningFailed(let message):
+            return message
+        case .sslError(let message):
+            return message
+        case .invalidConfig(let message):
+            return message
+        }
+    }
+
+    /// Standardized error code string for JS rejection.
+    var errorCode: String {
+        switch self {
+        case .unavailable: return "UNAVAILABLE"
+        case .cancelled: return "CANCELLED"
+        case .permissionDenied: return "PERMISSION_DENIED"
+        case .initFailed: return "INIT_FAILED"
+        case .invalidInput: return "INVALID_INPUT"
+        case .unknownType: return "UNKNOWN_TYPE"
+        case .notFound: return "NOT_FOUND"
+        case .conflict: return "CONFLICT"
+        case .timeout: return "TIMEOUT"
+        case .pinningFailed: return "PINNING_FAILED"
+        case .sslError: return "SSL_ERROR"
+        case .invalidConfig: return "INVALID_INPUT"
+        }
+    }
+}

package/ios/Sources/TLSFingerprintPlugin/error/TLSFingerprintErrorMessages.swift

@@ -0,0 +1,30 @@
+import Foundation
+
+/**
+ Canonical error messages shared across platforms.
+
+ These strings must remain byte-identical on iOS and Android.
+ */
+enum TLSFingerprintErrorMessages {
+    static let urlRequired = "url is required"
+    static let invalidUrlMustBeHttps = "Invalid URL. Must be https."
+    static let invalidUrl = "Invalid URL."
+    static let noFingerprintsProvided = "No fingerprints provided"
+    static let noHostFoundInUrl = "No host found in URL"
+    static let invalidFingerprintFormat = "Invalid fingerprint format"
+    static let unsupportedHost = "Unsupported host: %@"
+    static let pinningFailed = "Pinning failed"
+    static let excludedDomain = "Excluded domain"
+    static let timeout = "Timeout"
+    static let networkError = "Network error"
+    static let internalError = "Internal error"
+    static let invalidConfig = "Invalid configuration: %@"
+
+    static func unsupportedHost(_ value: String) -> String {
+        return String(format: unsupportedHost, value)
+    }
+
+    static func invalidConfig(_ value: String) -> String {
+        return String(format: invalidConfig, value)
+    }
+}

package/ios/Sources/TLSFingerprintPlugin/logger/TLSFingerprintLogger.swift

@@ -0,0 +1,69 @@
+import Capacitor
+
+/**
+ Centralized logger for the TLSFingerprint plugin.
+
+ Responsibilities:
+ - Provide a single logging entry point
+ - Support runtime-controlled verbose logging
+ - Keep logging behavior consistent across files
+
+ Forbidden:
+ - Controlling application logic
+ - Being queried for flow decisions
+ */
+enum TLSFingerprintLogger {
+
+    /**
+     Controls whether debug logs are printed.
+
+     This value MUST be set once during plugin initialization
+     based on static configuration.
+     */
+    static var verbose: Bool = false
+
+    /**
+     Prints a verbose / debug log message.
+
+     Debug logs are automatically silenced
+     when `verbose` is false.
+     */
+    static func debug(_ items: Any...) {
+        guard verbose else { return }
+        log(items)
+    }
+
+    /**
+     Prints an error log message.
+
+     Error logs are always printed regardless
+     of the verbose flag.
+     */
+    static func error(_ items: Any...) {
+        log(items)
+    }
+}
+
+// MARK: - Internal log printer
+
+/**
+ Low-level log printer with a consistent prefix.
+
+ This function MUST NOT be used outside this file.
+ */
+private func log(
+    _ items: [Any],
+    separator: String = " ",
+    terminator: String = "\n"
+) {
+    CAPLog.print("⚡️ TLSFingerprint -", terminator: separator)
+
+    for (index, item) in items.enumerated() {
+        CAPLog.print(
+            item,
+            terminator: index == items.count - 1
+                ? terminator
+                : separator
+        )
+    }
+}

package/ios/Sources/TLSFingerprintPlugin/model/TLSFingerprintResult.swift

@@ -0,0 +1,76 @@
+import Foundation
+
+/**
+ Canonical result model for TLS fingerprint validation operations on iOS.
+
+ This struct is exchanged between the native implementation (TLSFingerprintImpl)
+ and the bridge (TLSFingerprintPlugin) and serialized to JavaScript via a JSObject.
+
+ Fields mirror the public JS payload:
+ - actualFingerprint: server fingerprint used for matching
+ - fingerprintMatched: whether the fingerprint check succeeded (true) or not (false)
+ - matchedFingerprint: the fingerprint that matched (only present for fingerprint mode)
+ - excludedDomain: indicates an excluded-domain bypass (true when applicable)
+ - mode: active mode: "fingerprint" | "excluded"
+ - error: human-readable error (empty on success/match)
+ - errorCode: canonical error code string (empty on success)
+ */
+struct TLSFingerprintResult {
+    let actualFingerprint: String?
+    let fingerprintMatched: Bool
+    let matchedFingerprint: String?
+    let excludedDomain: Bool?
+    let mode: String?
+    let error: String?
+    let errorCode: String?
+
+    init(
+        actualFingerprint: String? = nil,
+        fingerprintMatched: Bool,
+        matchedFingerprint: String? = nil,
+        excludedDomain: Bool? = nil,
+        mode: String? = nil,
+        error: String? = nil,
+        errorCode: String? = nil
+    ) {
+        self.actualFingerprint = actualFingerprint
+        self.fingerprintMatched = fingerprintMatched
+        self.matchedFingerprint = matchedFingerprint
+        self.excludedDomain = excludedDomain
+        self.mode = mode
+        self.error = error
+        self.errorCode = errorCode
+    }
+
+    func toDictionary() -> [String: Any] {
+        var dict: [String: Any] = [
+            "fingerprintMatched": fingerprintMatched
+        ]
+
+        if let actualFingerprint = actualFingerprint {
+            dict["actualFingerprint"] = actualFingerprint
+        }
+
+        if let matchedFingerprint = matchedFingerprint {
+            dict["matchedFingerprint"] = matchedFingerprint
+        }
+
+        if let excludedDomain = excludedDomain {
+            dict["excludedDomain"] = excludedDomain
+        }
+
+        if let mode = mode {
+            dict["mode"] = mode
+        }
+
+        if let error = error {
+            dict["error"] = error
+        }
+
+        if let errorCode = errorCode {
+            dict["errorCode"] = errorCode
+        }
+
+        return dict
+    }
+}