[webview_flutter] Adds support to respond to recoverable SSL certificate errors (flutter#9150)

**tl;dr** This adds the `NavigationDelegate.onSslAuthError` method for recoverable SSL certificate errors.
Fixes flutter/flutter#36925

**Important Note**: This is a more niche feature that should only be used for logging errors or used in a development environment. See docs for [WebViewClient.onReceviedSslError](https://developer.android.com/reference/android/webkit/WebViewClient#onReceivedSslError(android.webkit.WebView,%20android.webkit.SslErrorHandler,%20android.net.http.SslError)). Therefore, I included multiple comments throughout that highly recommends calling `cancel()` and ensured that we call or set  `cancel`/`performDefaultHandling` when the method is not set with unit tests.

The respective platform callback methods are:
Android: [WebViewClient.onReceviedSslError](https://developer.android.com/reference/android/webkit/WebViewClient#onReceivedSslError(android.webkit.WebView,%20android.webkit.SslErrorHandler,%20android.net.http.SslError))
iOS/macOS: [WKNavigationDelegate(_:didReceive:completionHandler:)](https://developer.apple.com/documentation/webkit/wknavigationdelegate/webview(_:didreceive:completionhandler:))

The Android method is only called for recoverable SSL errors while the iOS/macOS method is called for all authentication related callbacks. So for iOS/macOS, the callback is only implemented when:

1. `URLAuthenticationChallenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust`
2. [SecTrustEvaluateWithError()](https://developer.apple.com/documentation/security/sectrustevaluatewitherror(_:_:)) returns false when passed `URLAuthenticationChallenge.protectionSpace.serverTrust`.
3. [SecTrustGetTrustResult()](https://developer.apple.com/documentation/security/sectrustgettrustresult(_:_:)) returns [SecTrustResultType.recoverableTrustFailure](https://developer.apple.com/documentation/security/sectrustresulttype/recoverabletrustfailure) when passed `URLAuthenticationChallenge.protectionSpace.serverTrust`.

This implementation only really provides the error description, certificate data, and the ability to proceed or cancel. Providing access to verify or manipulate a certificate seem to be outside the scope of a WebView plugin since [Android](https://developer.android.com/reference/javax/security/cert/package-summary) and [iOS/macOS](https://developer.apple.com/documentation/security) have an extensive separate library for them.

Providing the encoded data for the `X509Certificate` should be enough to use the certificate with another library.

A few platform differences to note:
1. Android provides a `String getUrl()` for the error while iOS/macOS provides a [URLProtectionSpace](https://developer.apple.com/documentation/foundation/urlprotectionspace) that provides `host`, `port`, `protocol`, and `proxyType`. I didn't think I would be able to create a full Dart `Uri` for iOS/macOS from these reliably, so each platform provides these values separately.
2. A certificate can have multiple errors, but only Android provides access to them. However, both platforms say that they provide access to the "primary" error, so I just provided that. A platform specific value for Android could be added later.

Side note: Android provides a [WebViewClient.onReceivedClientCertRequest](https://developer.android.com/reference/android/webkit/WebViewClient#onReceivedClientCertRequest(android.webkit.WebView,%20android.webkit.ClientCertRequest)) to read all certificate requests that don't get a recoverable error. A separate plugin method could be made to receive these.

Side Side note:
Old PR: flutter/plugins#2285
Fixes flutter/flutter#74609
Old quote about this feature from flutter/plugins#2285 (comment):
> By default, Flutter plugins should expect or enforce a secure environment, therefore we can not process this PR as-is. However, I can see a use case, especially during local development when it's just may not be feasible to have a properly signed https connection.

## Pre-Review Checklist

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: bparrishMines

packages/webview_flutter/webview_flutter/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.13.0
+
+* Adds support to respond to recoverable SSL certificate errors. See `NavigationDelegate(onSSlAuthError)`.
+
 ## 4.12.0
 
 * Adds support to set whether to draw the scrollbar. See

packages/webview_flutter/webview_flutter/example/pubspec.yaml

@@ -17,8 +17,8 @@ dependencies:
     # The example app is bundled with the plugin so we use a path dependency on
     # the parent directory to use the current plugin's version.
     path: ../
-  webview_flutter_android: ^4.5.0
-  webview_flutter_wkwebview: ^3.21.0
+  webview_flutter_android: ^4.7.0
+  webview_flutter_wkwebview: ^3.22.0
 
 dev_dependencies:
   build_runner: ^2.1.5
@@ -27,7 +27,7 @@ dev_dependencies:
     sdk: flutter
   integration_test:
     sdk: flutter
-  webview_flutter_platform_interface: ^2.12.0
+  webview_flutter_platform_interface: ^2.13.0
 
 flutter:
   uses-material-design: true

packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart

@@ -38,8 +38,11 @@ class NavigationDelegate {
   /// Constructs a [NavigationDelegate].
   ///
   /// {@template webview_fluttter.NavigationDelegate.constructor}
-  /// `onUrlChange`: invoked when the underlying web view changes to a new url.
-  /// `onHttpAuthRequest`: invoked when the web view is requesting authentication.
+  /// **`onUrlChange`:** invoked when the underlying web view changes to a new url.
+  /// **`onHttpAuthRequest`:** invoked when the web view is requesting authentication.
+  /// **`onSslAuthError`:** Invoked when the web view receives a recoverable SSL
+  ///   error for a certificate. The host application must call either
+  ///   [SslAuthError.cancel] or [SslAuthError.proceed].
   /// {@endtemplate}
   NavigationDelegate({
     FutureOr<NavigationDecision> Function(NavigationRequest request)?
@@ -51,6 +54,7 @@ class NavigationDelegate {
     void Function(UrlChange change)? onUrlChange,
     void Function(HttpAuthRequest request)? onHttpAuthRequest,
     void Function(HttpResponseError error)? onHttpError,
+    void Function(SslAuthError request)? onSslAuthError,
   }) : this.fromPlatformCreationParams(
           const PlatformNavigationDelegateCreationParams(),
           onNavigationRequest: onNavigationRequest,
@@ -61,6 +65,7 @@ class NavigationDelegate {
           onUrlChange: onUrlChange,
           onHttpAuthRequest: onHttpAuthRequest,
           onHttpError: onHttpError,
+          onSslAuthError: onSslAuthError,
         );
 
   /// Constructs a [NavigationDelegate] from creation params for a specific
@@ -105,6 +110,7 @@ class NavigationDelegate {
     void Function(UrlChange change)? onUrlChange,
     void Function(HttpAuthRequest request)? onHttpAuthRequest,
     void Function(HttpResponseError error)? onHttpError,
+    void Function(SslAuthError request)? onSslAuthError,
   }) : this.fromPlatform(
           PlatformNavigationDelegate(params),
           onNavigationRequest: onNavigationRequest,
@@ -115,6 +121,7 @@ class NavigationDelegate {
           onUrlChange: onUrlChange,
           onHttpAuthRequest: onHttpAuthRequest,
           onHttpError: onHttpError,
+          onSslAuthError: onSslAuthError,
         );
 
   /// Constructs a [NavigationDelegate] from a specific platform implementation.
@@ -130,6 +137,7 @@ class NavigationDelegate {
     void Function(UrlChange change)? onUrlChange,
     HttpAuthRequestCallback? onHttpAuthRequest,
     void Function(HttpResponseError error)? onHttpError,
+    void Function(SslAuthError request)? onSslAuthError,
   }) {
     if (onNavigationRequest != null) {
       platform.setOnNavigationRequest(onNavigationRequest!);
@@ -155,6 +163,13 @@ class NavigationDelegate {
     if (onHttpError != null) {
       platform.setOnHttpError(onHttpError);
     }
+    if (onSslAuthError != null) {
+      platform.setOnSSlAuthError(
+        (PlatformSslAuthError error) {
+          onSslAuthError(SslAuthError._fromPlatform(error));
+        },
+      );
+    }
   }
 
   /// Implementation of [PlatformNavigationDelegate] for the current platform.
@@ -184,3 +199,54 @@ class NavigationDelegate {
   /// Invoked when a resource loading error occurred.
   final WebResourceErrorCallback? onWebResourceError;
 }
+
+/// Represents an SSL error with the associated certificate.
+///
+/// The host application must call [cancel] or, contrary to secure web
+/// communication standards, [proceed] to provide the web view's response to the
+/// error. [proceed] should generally only be used in test environments, as
+/// using it in production can expose users to security and privacy risks.
+///
+/// ## Platform-Specific Features
+/// This class contains an underlying implementation provided by the current
+/// platform. Once a platform implementation is imported, the examples below
+/// can be followed to use features provided by a platform's implementation.
+///
+/// Below is an example of accessing the platform-specific implementation for
+/// iOS and Android:
+///
+/// ```dart
+/// final SslAuthError error = ...;
+///
+/// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+///   final WebKitSslAuthError webKitError =
+///       error.platform as WebKitSslAuthError;
+/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+///   final AndroidSslAuthError androidError =
+///       error.platform as AndroidSslAuthError;
+/// }
+/// ```
+class SslAuthError {
+  SslAuthError._fromPlatform(this.platform);
+
+  /// An implementation of [PlatformSslAuthError] for the current platform.
+  final PlatformSslAuthError platform;
+
+  /// The certificate associated with this error.
+  X509Certificate? get certificate => platform.certificate;
+
+  /// Instructs the WebView that encountered the SSL certificate error to
+  /// terminate communication with the server.
+  ///
+  /// The host application must call this method to prevent a resource from
+  /// loading when an SSL certificate is invalid.
+  Future<void> cancel() => platform.cancel();
+
+  /// Instructs the WebView that encountered the SSL certificate error to ignore
+  /// the error and continue communicating with the server.
+  ///
+  /// **Warning:** Calling [proceed] in a production environment is strongly
+  /// discouraged, as an invalid SSL certificate means that the connection is
+  /// not secure, so proceeding can expose users to security and privacy risks.
+  Future<void> proceed() => platform.proceed();
+}

packages/webview_flutter/webview_flutter/lib/webview_flutter.dart

@@ -36,7 +36,8 @@ export 'package:webview_flutter_platform_interface/webview_flutter_platform_inte
         WebViewCredential,
         WebViewOverScrollMode,
         WebViewPermissionResourceType,
-        WebViewPlatform;
+        WebViewPlatform,
+        X509Certificate;
 
 export 'src/navigation_delegate.dart';
 export 'src/webview_controller.dart';

packages/webview_flutter/webview_flutter/pubspec.yaml

@@ -2,7 +2,7 @@ name: webview_flutter
 description: A Flutter plugin that provides a WebView widget backed by the system webview.
 repository: https://github.com/flutter/packages/tree/main/packages/webview_flutter/webview_flutter
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+webview%22
-version: 4.12.0
+version: 4.13.0
 
 environment:
   sdk: ^3.6.0
@@ -21,9 +21,9 @@ flutter:
 dependencies:
   flutter:
     sdk: flutter
-  webview_flutter_android: ^4.5.0
-  webview_flutter_platform_interface: ^2.12.0
-  webview_flutter_wkwebview: ^3.21.0
+  webview_flutter_android: ^4.7.0
+  webview_flutter_platform_interface: ^2.13.0
+  webview_flutter_wkwebview: ^3.22.0
 
 dev_dependencies:
   build_runner: ^2.1.5

packages/webview_flutter/webview_flutter/test/navigation_delegate_test.dart

@@ -11,7 +11,11 @@ import 'package:webview_flutter_platform_interface/webview_flutter_platform_inte
 
 import 'navigation_delegate_test.mocks.dart';
 
-@GenerateMocks(<Type>[WebViewPlatform, PlatformNavigationDelegate])
+@GenerateMocks(<Type>[
+  WebViewPlatform,
+  PlatformNavigationDelegate,
+  PlatformSslAuthError,
+])
 void main() {
   group('NavigationDelegate', () {
     test('onNavigationRequest', () async {
@@ -111,6 +115,28 @@ void main() {
 
       verify(delegate.platform.setOnHttpError(onHttpError));
     });
+
+    test('onSslAuthError', () async {
+      WebViewPlatform.instance = TestWebViewPlatform();
+
+      final NavigationDelegate delegate = NavigationDelegate(
+        onSslAuthError: expectAsync1((SslAuthError error) {
+          error.proceed();
+        }),
+      );
+
+      final void Function(PlatformSslAuthError) callback = verify(
+              (delegate.platform as MockPlatformNavigationDelegate)
+                  .setOnSSlAuthError(captureAny))
+          .captured
+          .single as void Function(PlatformSslAuthError);
+
+      final MockPlatformSslAuthError mockPlatformError =
+          MockPlatformSslAuthError();
+      callback(mockPlatformError);
+
+      verify(mockPlatformError.proceed());
+    });
   });
 }
 

packages/webview_flutter/webview_flutter/test/navigation_delegate_test.mocks.dart

@@ -6,8 +6,11 @@
 import 'dart:async' as _i8;
 
 import 'package:mockito/mockito.dart' as _i1;
+import 'package:mockito/src/dummies.dart' as _i10;
 import 'package:webview_flutter_platform_interface/src/platform_navigation_delegate.dart'
     as _i3;
+import 'package:webview_flutter_platform_interface/src/platform_ssl_auth_error.dart'
+    as _i9;
 import 'package:webview_flutter_platform_interface/src/platform_webview_controller.dart'
     as _i4;
 import 'package:webview_flutter_platform_interface/src/platform_webview_cookie_manager.dart'
@@ -211,4 +214,47 @@ class MockPlatformNavigationDelegate extends _i1.Mock
         returnValue: _i8.Future<void>.value(),
         returnValueForMissingStub: _i8.Future<void>.value(),
       ) as _i8.Future<void>);
+
+  @override
+  _i8.Future<void> setOnSSlAuthError(
+    _i3.SslAuthErrorCallback? onSslAuthError,
+  ) =>
+      (super.noSuchMethod(
+        Invocation.method(#setOnSSlAuthError, [onSslAuthError]),
+        returnValue: _i8.Future<void>.value(),
+        returnValueForMissingStub: _i8.Future<void>.value(),
+      ) as _i8.Future<void>);
+}
+
+/// A class which mocks [PlatformSslAuthError].
+///
+/// See the documentation for Mockito's code generation for more information.
+class MockPlatformSslAuthError extends _i1.Mock
+    implements _i9.PlatformSslAuthError {
+  MockPlatformSslAuthError() {
+    _i1.throwOnMissingStub(this);
+  }
+
+  @override
+  String get description => (super.noSuchMethod(
+        Invocation.getter(#description),
+        returnValue: _i10.dummyValue<String>(
+          this,
+          Invocation.getter(#description),
+        ),
+      ) as String);
+
+  @override
+  _i8.Future<void> proceed() => (super.noSuchMethod(
+        Invocation.method(#proceed, []),
+        returnValue: _i8.Future<void>.value(),
+        returnValueForMissingStub: _i8.Future<void>.value(),
+      ) as _i8.Future<void>);
+
+  @override
+  _i8.Future<void> cancel() => (super.noSuchMethod(
+        Invocation.method(#cancel, []),
+        returnValue: _i8.Future<void>.value(),
+        returnValueForMissingStub: _i8.Future<void>.value(),
+      ) as _i8.Future<void>);
 }

packages/webview_flutter/webview_flutter/test/webview_controller_test.mocks.dart

@@ -458,4 +458,14 @@ class MockPlatformNavigationDelegate extends _i1.Mock
         returnValue: _i5.Future<void>.value(),
         returnValueForMissingStub: _i5.Future<void>.value(),
       ) as _i5.Future<void>);
+
+  @override
+  _i5.Future<void> setOnSSlAuthError(
+    _i6.SslAuthErrorCallback? onSslAuthError,
+  ) =>
+      (super.noSuchMethod(
+        Invocation.method(#setOnSSlAuthError, [onSslAuthError]),
+        returnValue: _i5.Future<void>.value(),
+        returnValueForMissingStub: _i5.Future<void>.value(),
+      ) as _i5.Future<void>);
 }

packages/webview_flutter/webview_flutter/test/webview_flutter_export_test.dart

@@ -30,6 +30,7 @@ void main() {
         main_file.PlatformWebViewPermissionRequest;
         main_file.PlatformWebViewWidgetCreationParams;
         main_file.ProgressCallback;
+        main_file.UrlChange;
         main_file.WebViewOverScrollMode;
         main_file.WebViewPermissionResourceType;
         main_file.WebResourceError;
@@ -39,7 +40,7 @@ void main() {
         main_file.WebResourceErrorType;
         main_file.WebResourceRequest;
         main_file.WebResourceResponse;
-        main_file.UrlChange;
+        main_file.X509Certificate;
       },
     );
   });