@cap-kit/tls-fingerprint 8.0.0

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sources":["esm/definitions.js","esm/index.js","esm/version.js","esm/web.js"],"sourcesContent":["/// <reference types=\"@capacitor/cli\" />\n// -----------------------------------------------------------------------------\n// Enums\n// -----------------------------------------------------------------------------\n/**\n * Standardized error codes for programmatic handling of TLS fingerprint failures.\n *\n * Errors are delivered via Promise rejection as `CapacitorException`\n * with one of the following codes.\n *\n * @since 8.0.0\n */\nexport var TLSFingerprintErrorCode;\n(function (TLSFingerprintErrorCode) {\n    /** Required data is missing or the feature is not available. */\n    TLSFingerprintErrorCode[\"UNAVAILABLE\"] = \"UNAVAILABLE\";\n    /** The user cancelled an interactive flow. */\n    TLSFingerprintErrorCode[\"CANCELLED\"] = \"CANCELLED\";\n    /** The user denied a required permission or the feature is disabled. */\n    TLSFingerprintErrorCode[\"PERMISSION_DENIED\"] = \"PERMISSION_DENIED\";\n    /** The TLS fingerprint operation failed due to a runtime or initialization error. */\n    TLSFingerprintErrorCode[\"INIT_FAILED\"] = \"INIT_FAILED\";\n    /** The input provided to the plugin method is invalid, missing, or malformed. */\n    TLSFingerprintErrorCode[\"INVALID_INPUT\"] = \"INVALID_INPUT\";\n    /** Invalid or unsupported input was provided. */\n    TLSFingerprintErrorCode[\"UNKNOWN_TYPE\"] = \"UNKNOWN_TYPE\";\n    /** The requested resource does not exist. */\n    TLSFingerprintErrorCode[\"NOT_FOUND\"] = \"NOT_FOUND\";\n    /** The operation conflicts with the current state. */\n    TLSFingerprintErrorCode[\"CONFLICT\"] = \"CONFLICT\";\n    /** The operation did not complete within the expected time. */\n    TLSFingerprintErrorCode[\"TIMEOUT\"] = \"TIMEOUT\";\n    /** The server certificate fingerprint did not match any expected fingerprint. */\n    TLSFingerprintErrorCode[\"PINNING_FAILED\"] = \"PINNING_FAILED\";\n    /** The request host matched an excluded domain. */\n    TLSFingerprintErrorCode[\"EXCLUDED_DOMAIN\"] = \"EXCLUDED_DOMAIN\";\n    /** Network connectivity or TLS handshake error. */\n    TLSFingerprintErrorCode[\"NETWORK_ERROR\"] = \"NETWORK_ERROR\";\n    /** SSL/TLS specific error (certificate expired, handshake failure, etc.). */\n    TLSFingerprintErrorCode[\"SSL_ERROR\"] = \"SSL_ERROR\";\n})(TLSFingerprintErrorCode || (TLSFingerprintErrorCode = {}));\n//# sourceMappingURL=definitions.js.map","import { registerPlugin } from '@capacitor/core';\n/**\n * The TLSFingerprint plugin instance.\n * It lazily loads the Web implementation when running in a browser.\n */\nconst TLSFingerprint = registerPlugin('TLSFingerprint', {\n    web: () => import('./web').then((m) => new m.TLSFingerprintWeb()),\n});\nexport * from './definitions';\nexport { TLSFingerprint };\n//# sourceMappingURL=index.js.map","// This file is automatically generated. Do not modify manually.\nexport const PLUGIN_VERSION = '8.0.0';\n//# sourceMappingURL=version.js.map","import { WebPlugin } from '@capacitor/core';\nimport { PLUGIN_VERSION } from './version';\n/**\n * Web implementation of the TLSFingerprint plugin.\n *\n * This implementation exists to satisfy Capacitor's multi-platform contract.\n * TLS fingerprinting is not supported in web browsers.\n *\n * All methods follow the standard Promise rejection model:\n * - unsupported features reject with UNAVAILABLE\n */\nexport class TLSFingerprintWeb extends WebPlugin {\n    constructor() {\n        super();\n    }\n    /**\n     * Checks a single SSL certificate against the expected fingerprint.\n     * @param options - Unused on web platform.\n     * @throws CapacitorException indicating unimplemented functionality.\n     */\n    async checkCertificate(options) {\n        void options;\n        throw this.unimplemented();\n    }\n    /**\n     * Checks multiple SSL certificates against their expected fingerprints.\n     * @param options - Unused on web platform.\n     * @throws CapacitorException indicating unimplemented functionality.\n     */\n    async checkCertificates(options) {\n        void options;\n        throw this.unimplemented();\n    }\n    // -----------------------------------------------------------------------------\n    // Plugin Info\n    // -----------------------------------------------------------------------------\n    /**\n     * Returns the plugin version.\n     *\n     * On the Web, this value represents the JavaScript package version\n     * rather than a native implementation.\n     */\n    async getPluginVersion() {\n        return { version: PLUGIN_VERSION };\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["TLSFingerprintErrorCode","registerPlugin","WebPlugin"],"mappings":";;;IAAA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;AACWA;IACX,CAAC,UAAU,uBAAuB,EAAE;IACpC;IACA,IAAI,uBAAuB,CAAC,aAAa,CAAC,GAAG,aAAa;IAC1D;IACA,IAAI,uBAAuB,CAAC,WAAW,CAAC,GAAG,WAAW;IACtD;IACA,IAAI,uBAAuB,CAAC,mBAAmB,CAAC,GAAG,mBAAmB;IACtE;IACA,IAAI,uBAAuB,CAAC,aAAa,CAAC,GAAG,aAAa;IAC1D;IACA,IAAI,uBAAuB,CAAC,eAAe,CAAC,GAAG,eAAe;IAC9D;IACA,IAAI,uBAAuB,CAAC,cAAc,CAAC,GAAG,cAAc;IAC5D;IACA,IAAI,uBAAuB,CAAC,WAAW,CAAC,GAAG,WAAW;IACtD;IACA,IAAI,uBAAuB,CAAC,UAAU,CAAC,GAAG,UAAU;IACpD;IACA,IAAI,uBAAuB,CAAC,SAAS,CAAC,GAAG,SAAS;IAClD;IACA,IAAI,uBAAuB,CAAC,gBAAgB,CAAC,GAAG,gBAAgB;IAChE;IACA,IAAI,uBAAuB,CAAC,iBAAiB,CAAC,GAAG,iBAAiB;IAClE;IACA,IAAI,uBAAuB,CAAC,eAAe,CAAC,GAAG,eAAe;IAC9D;IACA,IAAI,uBAAuB,CAAC,WAAW,CAAC,GAAG,WAAW;IACtD,CAAC,EAAEA,+BAAuB,KAAKA,+BAAuB,GAAG,EAAE,CAAC,CAAC;;ICvC7D;IACA;IACA;IACA;AACK,UAAC,cAAc,GAAGC,mBAAc,CAAC,gBAAgB,EAAE;IACxD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACrE,CAAC;;ICPD;IACO,MAAM,cAAc,GAAG,OAAO;;ICCrC;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACO,MAAM,iBAAiB,SAASC,cAAS,CAAC;IACjD,IAAI,WAAW,GAAG;IAClB,QAAQ,KAAK,EAAE;IACf,IAAI;IACJ;IACA;IACA;IACA;IACA;IACA,IAAI,MAAM,gBAAgB,CAAC,OAAO,EAAE;IAEpC,QAAQ,MAAM,IAAI,CAAC,aAAa,EAAE;IAClC,IAAI;IACJ;IACA;IACA;IACA;IACA;IACA,IAAI,MAAM,iBAAiB,CAAC,OAAO,EAAE;IAErC,QAAQ,MAAM,IAAI,CAAC,aAAa,EAAE;IAClC,IAAI;IACJ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,IAAI,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE;IAC1C,IAAI;IACJ;;;;;;;;;;;;;;;"}

package/ios/Sources/TLSFingerprintPlugin/TLSFingerprintDelegate.swift

@@ -0,0 +1,365 @@
+import Foundation
+import Security
+
+/**
+ URLSession delegate responsible for performing
+ TLS fingerprint validation during the TLS handshake phase.
+
+ SECURITY MODEL:
+ This plugin validates fingerprint equality only and does not
+ enforce system trust evaluation.
+
+ Responsibilities:
+ - Intercept TLS authentication challenges
+ - Evaluate the server trust object
+ - Apply TLS fingerprint strategies
+ - Return structured validation results
+
+ Supported strategies (evaluation order):
+ 1. Excluded domain bypass
+ 2. Fingerprint-based validation (leaf comparison)
+
+ Forbidden:
+ - Referencing Capacitor APIs
+ - Throwing JavaScript-facing errors
+ - Performing configuration lookups
+ - Managing bridge lifecycle
+
+ Architectural notes:
+ - This class operates purely at the networking layer.
+ - It is stateless beyond the injected configuration.
+ - It must always call the completion handler exactly once.
+ */
+final class TLSFingerprintDelegate: NSObject, URLSessionDelegate, URLSessionTaskDelegate {
+
+    // MARK: - Properties
+
+    /**
+     The URLSession that owns this delegate and executes the request.
+     Set via setSession() after delegate initialization.
+     */
+    private var session: URLSession?
+
+    /**
+     Tracks whether the completion handler has already been called.
+     Used to prevent double-calling on timeout or other terminal errors.
+     */
+    private var hasCompleted = false
+
+    /**
+     Lock for thread-safe completion tracking.
+     */
+    private let completionLock = NSLock()
+
+    /**
+     Normalized expected fingerprints.
+
+     All fingerprints are normalized at initialization time
+     to guarantee deterministic comparison.
+     */
+    private let expectedFingerprints: [String]
+
+    /**
+     Lowercased list of excluded domains.
+
+     Matching rules:
+     - Exact hostname match
+     - Subdomain match
+
+     Example:
+     - excluded: example.com
+     - matches: example.com, api.example.com
+     */
+    private let excludedDomains: [String]
+
+    /**
+     Completion handler returning the raw result
+     of the SSL pinning operation.
+
+     The delegate must ALWAYS invoke this exactly once.
+     */
+    private let completion: (TLSFingerprintResult) -> Void
+
+    /**
+     Controls verbose native logging.
+
+     Logging decisions are made outside this class.
+     */
+    private let verboseLogging: Bool
+
+    // MARK: - Initialization
+
+    /**
+     Initializes the TLSFingerprintDelegate.
+
+     - Parameters:
+     - expectedFingerprints: Allowed SHA-256 fingerprints.
+     - excludedDomains: Hostnames that bypass SSL pinning.
+     - completion: Completion handler returning structured result data.
+     - verboseLogging: Enables verbose native logging.
+
+     Design notes:
+     - All inputs are normalized and stored.
+     - No external configuration access is performed.
+     - Session must be set via setSession() before use.
+     */
+    init(
+        expectedFingerprints: [String],
+        excludedDomains: [String] = [],
+        completion: @escaping (TLSFingerprintResult) -> Void,
+        verboseLogging: Bool
+    ) {
+        self.expectedFingerprints =
+            expectedFingerprints.map {
+                TLSFingerprintUtils.normalizeFingerprint($0)
+            }
+
+        self.excludedDomains =
+            excludedDomains.map { $0.lowercased() }
+
+        self.verboseLogging = verboseLogging
+
+        self.completion = completion
+        super.init()
+    }
+
+    /**
+     Sets the URLSession that owns this delegate.
+
+     Must be called before the session executes any task.
+     The session will be invalidated when completion is called.
+     */
+    func setSession(_ session: URLSession) {
+        self.session = session
+    }
+
+    // MARK: - Completion Handler
+
+    /**
+     Attempts to mark completion atomically.
+     Returns true if this call successfully marked completion (no prior completion).
+     Used by timeout handlers to prevent race conditions.
+     */
+    func trySetCompleted() -> Bool {
+        completionLock.lock()
+        defer { completionLock.unlock() }
+
+        if hasCompleted {
+            return false
+        }
+        hasCompleted = true
+        return true
+    }
+
+    /**
+     Helper method to complete the request and invalidate the session.
+     Ensures session is invalidated exactly once.
+     */
+    private func completeWithResult(_ result: TLSFingerprintResult) {
+        completionLock.lock()
+        guard !hasCompleted else {
+            completionLock.unlock()
+            return
+        }
+        hasCompleted = true
+        completionLock.unlock()
+
+        session?.invalidateAndCancel()
+        completion(result)
+    }
+
+    // MARK: - URLSessionDelegate
+
+    /**
+     Intercepts the TLS authentication challenge
+     and applies the configured TLS fingerprint strategy.
+
+     IMPORTANT SECURITY NOTES:
+
+     - The delegate controls whether the connection proceeds.
+     - If validation fails, the challenge is cancelled.
+     - The completion handler MUST always be invoked.
+     - Trust evaluation behavior depends on selected mode.
+
+     This plugin validates fingerprint equality only and does not
+     enforce system trust evaluation.
+
+     Mode behavior:
+
+     1. Excluded Mode
+     - Bypasses fingerprint validation entirely.
+     - Uses permissive trust handling.
+
+     2. Fingerprint Mode
+     - Does NOT evaluate system trust.
+     - Compares only the leaf certificate fingerprint.
+     */
+    func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge,
+        completionHandler: @escaping (
+            URLSession.AuthChallengeDisposition,
+            URLCredential?
+        ) -> Void
+    ) {
+
+        guard let trust = challenge.protectionSpace.serverTrust else {
+            completionHandler(.cancelAuthenticationChallenge, nil)
+            completeWithResult(TLSFingerprintResult(
+                fingerprintMatched: false,
+                error: TLSFingerprintErrorMessages.internalError,
+                errorCode: "INIT_FAILED"
+            ))
+            return
+        }
+
+        let host = challenge.protectionSpace.host.lowercased()
+
+        // =========================================================
+        // EXCLUDED DOMAIN MODE (bypass fingerprint validation)
+        // =========================================================
+
+        /**
+         If the current host matches an excluded domain,
+         fingerprint validation is bypassed.
+         The connection uses a permissive trust manager.
+         System trust chain is NOT explicitly evaluated.
+         We still compute and return the actual fingerprint for parity.
+         */
+        if excludedDomains.contains(where: {
+            host == $0 || host.hasSuffix("." + $0)
+        }) {
+
+            TLSFingerprintLogger.debug("TLSFingerprint excluded domain:", host)
+
+            guard let certificate =
+                    TLSFingerprintUtils.leafCertificate(from: trust)
+            else {
+                completionHandler(.cancelAuthenticationChallenge, nil)
+                completeWithResult(TLSFingerprintResult(
+                    fingerprintMatched: false,
+                    error: TLSFingerprintErrorMessages.internalError,
+                    errorCode: "INIT_FAILED"
+                ))
+                return
+            }
+
+            let actualFingerprint =
+                TLSFingerprintUtils.normalizeFingerprint(
+                    TLSFingerprintUtils.sha256Fingerprint(from: certificate)
+                )
+
+            completionHandler(.useCredential, URLCredential(trust: trust))
+
+            completeWithResult(TLSFingerprintResult(
+                actualFingerprint: actualFingerprint,
+                fingerprintMatched: true,
+                excludedDomain: true,
+                mode: "excluded",
+                error: TLSFingerprintErrorMessages.excludedDomain,
+                errorCode: "EXCLUDED_DOMAIN"
+            ))
+
+            return
+        }
+
+        guard let certificate =
+                TLSFingerprintUtils.leafCertificate(from: trust)
+        else {
+            completionHandler(.cancelAuthenticationChallenge, nil)
+            completeWithResult(TLSFingerprintResult(
+                fingerprintMatched: false,
+                error: TLSFingerprintErrorMessages.internalError,
+                errorCode: "INIT_FAILED"
+            ))
+            return
+        }
+
+        let actualFingerprint =
+            TLSFingerprintUtils.normalizeFingerprint(
+                TLSFingerprintUtils.sha256Fingerprint(from: certificate)
+            )
+
+        let matchedFingerprint =
+            expectedFingerprints.first {
+                $0 == actualFingerprint
+            }
+
+        let matched = matchedFingerprint != nil
+
+        TLSFingerprintLogger.debug(
+            "TLSFingerprint matched:",
+            "\(matched)"
+        )
+
+        completionHandler(
+            matched
+                ? .useCredential
+                : .cancelAuthenticationChallenge,
+            matched
+                ? URLCredential(trust: trust)
+                : nil
+        )
+
+        completeWithResult(TLSFingerprintResult(
+            actualFingerprint: actualFingerprint,
+            fingerprintMatched: matched,
+            matchedFingerprint: matchedFingerprint,
+            mode: "fingerprint",
+            error: matched ? "" : TLSFingerprintErrorMessages.pinningFailed,
+            errorCode: matched ? "" : "PINNING_FAILED"
+        ))
+    }
+
+    // MARK: - URLSessionTaskDelegate
+
+    /**
+     Handles task-level events including timeouts.
+
+     This method is called when the task completes, allowing us
+     to detect and handle timeout errors that may occur before
+     or during the authentication challenge.
+     */
+    func urlSession(
+        _ session: URLSession,
+        task: URLSessionTask,
+        didCompleteWithError error: Error?
+    ) {
+        guard trySetCompleted() else { return }
+
+        if let error = error {
+            let nsError = error as NSError
+
+            // Timeout
+            if nsError.code == NSURLErrorTimedOut {
+                session.invalidateAndCancel()
+                completion(TLSFingerprintResult(
+                    fingerprintMatched: false,
+                    error: TLSFingerprintErrorMessages.timeout,
+                    errorCode: "TIMEOUT"
+                ))
+            }
+            // Common network errors (non-timeout)
+            else if nsError.domain == NSURLErrorDomain,
+                    [NSURLErrorNotConnectedToInternet,
+                     NSURLErrorNetworkConnectionLost,
+                     NSURLErrorCannotFindHost,
+                     NSURLErrorCannotConnectToHost].contains(nsError.code) {
+                session.invalidateAndCancel()
+                completion(TLSFingerprintResult(
+                    fingerprintMatched: false,
+                    error: TLSFingerprintErrorMessages.networkError,
+                    errorCode: "NETWORK_ERROR"
+                ))
+            } else {
+                // Fallback for other errors
+                session.invalidateAndCancel()
+                completion(TLSFingerprintResult(
+                    fingerprintMatched: false,
+                    error: TLSFingerprintErrorMessages.networkError,
+                    errorCode: "NETWORK_ERROR"
+                ))
+            }
+        }
+    }
+}

package/ios/Sources/TLSFingerprintPlugin/TLSFingerprintImpl.swift

@@ -0,0 +1,275 @@
+import Foundation
+
+/**
+ Native iOS implementation for the TLSFingerprint plugin.
+
+ Responsibilities:
+ - Perform platform-specific operations
+ - Throw typed TLSFingerprintError values on failure
+
+ Forbidden:
+ - Accessing CAPPluginCall
+ - Referencing Capacitor APIs
+ - Constructing JS payloads
+ */
+@objc public final class TLSFingerprintImpl: NSObject {
+
+    // MARK: - Constants
+
+    private static let timeoutSeconds: TimeInterval = 10
+
+    // MARK: - Properties
+
+    /**
+     Static plugin configuration.
+
+     Injected once during plugin initialization.
+     Must not be mutated after being set.
+     */
+    private var config: TLSFingerprintConfig?
+
+    // Initializer
+    override init() {
+        super.init()
+    }
+
+    // MARK: - Configuration
+
+    /**
+     Applies static plugin configuration.
+
+     This method MUST be called exactly once
+     from the Plugin layer during `load()`.
+
+     Responsibilities:
+     - Store immutable configuration
+     - Configure runtime logging behavior
+     */
+    func applyConfig(_ config: TLSFingerprintConfig) {
+        precondition(
+            self.config == nil,
+            "TLSFingerprintImpl.applyConfig(_:) must be called exactly once"
+        )
+        self.config = config
+        TLSFingerprintLogger.verbose = config.verboseLogging
+
+        TLSFingerprintLogger.debug(
+            "Configuration applied. Verbose logging:",
+            config.verboseLogging
+        )
+    }
+
+    // MARK: - 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 is available.
+     */
+    func checkCertificate(
+        urlString: String,
+        fingerprintFromArgs: String?
+    ) async throws -> TLSFingerprintResult {
+
+        let fingerprint =
+            fingerprintFromArgs ??
+            config?.fingerprint
+
+        guard let expectedFingerprint = fingerprint else {
+            throw TLSFingerprintError.unavailable(
+                TLSFingerprintErrorMessages.noFingerprintsProvided
+            )
+        }
+
+        return try await performCheck(
+            urlString: urlString,
+            fingerprints: [expectedFingerprint]
+        )
+    }
+
+    // MARK: - 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 the server certificate.
+
+     - Throws: `TLSFingerprintError.unavailable`
+     if no fingerprints are available.
+     */
+    func checkCertificates(
+        urlString: String,
+        fingerprintsFromArgs: [String]?
+    ) async throws -> TLSFingerprintResult {
+
+        let fingerprints =
+            fingerprintsFromArgs ??
+            config?.fingerprints
+
+        guard let fps = fingerprints, !fps.isEmpty else {
+            throw TLSFingerprintError.unavailable(
+                TLSFingerprintErrorMessages.noFingerprintsProvided
+            )
+        }
+
+        return try await performCheck(
+            urlString: urlString,
+            fingerprints: fps
+        )
+    }
+
+    // MARK: - Shared implementation
+
+    /**
+     Performs SSL fingerprint validation for a given HTTPS URL.
+
+     Evaluation order:
+
+     1. Excluded domains → bypass validation entirely.
+     2. Fingerprint-based validation.
+
+     This method uses async/await and wraps the URLSession
+     delegate flow inside a continuation.
+
+     - Throws:
+     - `TLSFingerprintError.unknownType`
+     - `TLSFingerprintError.initFailed`
+     */
+    private func performCheck(
+        urlString: String,
+        fingerprints: [String]
+    ) async throws -> TLSFingerprintResult {
+
+        guard let url = TLSFingerprintUtils.httpsURL(from: urlString) else {
+            throw TLSFingerprintError.unknownType(
+                TLSFingerprintErrorMessages.invalidUrlMustBeHttps
+            )
+        }
+
+        let host = url.host?.lowercased() ?? ""
+
+        // -----------------------------------------------------------------------
+        // EXCLUDED DOMAIN MODE
+        // -----------------------------------------------------------------------
+
+        /**
+         If the request host matches an excluded domain,
+         we still perform the connection to retrieve the actual fingerprint
+         for parity with Android behavior.
+
+         The connection uses a permissive trust manager.
+         System trust chain is NOT explicitly evaluated.
+         */
+        if isExcludedDomain(host) {
+            TLSFingerprintLogger.debug("TLSFingerprint excluded domain:", host)
+
+            return try await withCheckedThrowingContinuation { continuation in
+                let configuration = URLSessionConfiguration.ephemeral
+                configuration.timeoutIntervalForRequest = Self.timeoutSeconds
+                configuration.timeoutIntervalForResource = Self.timeoutSeconds
+
+                let delegate = TLSFingerprintDelegate(
+                    expectedFingerprints: [],
+                    excludedDomains: config?.excludedDomains ?? [],
+                    completion: { result in
+                        continuation.resume(returning: result)
+                    },
+                    verboseLogging: config?.verboseLogging ?? false
+                )
+
+                let session = URLSession(
+                    configuration: configuration,
+                    delegate: delegate,
+                    delegateQueue: nil
+                )
+
+                delegate.setSession(session)
+
+                let timeoutWorkItem = DispatchWorkItem { [weak delegate] in
+                    guard let delegate = delegate else { return }
+                    let shouldTimeout = delegate.trySetCompleted()
+                    if shouldTimeout {
+                        session.invalidateAndCancel()
+                        continuation.resume(returning: TLSFingerprintResult(
+                            fingerprintMatched: false,
+                            error: TLSFingerprintErrorMessages.timeout,
+                            errorCode: "TIMEOUT"
+                        ))
+                    }
+                }
+
+                DispatchQueue.global().asyncAfter(deadline: .now() + Self.timeoutSeconds, execute: timeoutWorkItem)
+
+                session.dataTask(with: url).resume()
+            }
+        }
+
+        return try await withCheckedThrowingContinuation { continuation in
+
+            let configuration = URLSessionConfiguration.ephemeral
+            configuration.timeoutIntervalForRequest = 10
+            configuration.timeoutIntervalForResource = 10
+
+            let delegate = TLSFingerprintDelegate(
+                expectedFingerprints: fingerprints,
+                excludedDomains: config?.excludedDomains ?? [],
+                completion: { result in
+                    continuation.resume(returning: result)
+                },
+                verboseLogging: config?.verboseLogging ?? false
+            )
+
+            let session = URLSession(
+                configuration: configuration,
+                delegate: delegate,
+                delegateQueue: nil
+            )
+
+            delegate.setSession(session)
+
+            let timeoutWorkItem = DispatchWorkItem { [weak delegate] in
+                guard let delegate = delegate else { return }
+                let shouldTimeout = delegate.trySetCompleted()
+                if shouldTimeout {
+                    session.invalidateAndCancel()
+                    continuation.resume(returning: TLSFingerprintResult(
+                        fingerprintMatched: false,
+                        error: TLSFingerprintErrorMessages.timeout,
+                        errorCode: "TIMEOUT"
+                    ))
+                }
+            }
+
+            DispatchQueue.global().asyncAfter(deadline: .now() + Self.timeoutSeconds, execute: timeoutWorkItem)
+
+            session.dataTask(with: url).resume()
+        }
+    }
+
+    /**
+     Determines whether the given host
+     matches one of the configured excluded domains.
+
+     Matching rules:
+     - Exact match
+     - Subdomain match
+
+     Matching is case-insensitive.
+     */
+    private func isExcludedDomain(_ host: String) -> Bool {
+        let hostLower = host.lowercased().trimmingCharacters(in: .whitespacesAndNewlines)
+        return config?.excludedDomains.contains { excluded in
+            let excludedLower = excluded.lowercased().trimmingCharacters(in: .whitespacesAndNewlines)
+            // Match exact domain or any subdomain (e.g., api.example.com matches example.com)
+            return hostLower == excludedLower || hostLower.hasSuffix("." + excludedLower)
+        } ?? false
+    }
+}