feat(plugins): Add plugin support for auth challenge responses

Closes GH-1212.

Co-Authored-By: Christopher J. Brody <chris.brody+brodybits@gmail.com>

CordovaLib/Classes/Private/Plugins/CDVWebViewEngine/CDVWebViewEngine.m

@@ -602,6 +602,22 @@ - (void) webView: (WKWebView *) webView decidePolicyForNavigationAction: (WKNavi
     return decisionHandler(NO);
 }
 
+- (void)webView:(WKWebView *)webView didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential * _Nullable))completionHandler
+{
+    CDVViewController* vc = (CDVViewController*)self.viewController;
+
+    for (CDVPlugin *plugin in vc.enumerablePlugins) {
+        if ([plugin respondsToSelector:@selector(willHandleAuthenticationChallenge:completionHandler:)]) {
+            CDVPlugin <CDVPluginAuthenticationHandler> *challengePlugin = (CDVPlugin <CDVPluginAuthenticationHandler> *)plugin;
+            if ([challengePlugin willHandleAuthenticationChallenge:challenge completionHandler:completionHandler]) {
+                return;
+            }
+        }
+    }
+
+    completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
+}
+
 #pragma mark - Plugin interface
 
 - (void)allowsBackForwardNavigationGestures:(CDVInvokedUrlCommand*)command;

CordovaLib/Classes/Public/CDVPlugin.m

@@ -142,7 +142,7 @@ - (void)handleOpenURL:(NSNotification*)notification
 /*
     NOTE: calls into JavaScript must not call or trigger any blocking UI, like alerts
  */
-- (void)handleOpenURLWithApplicationSourceAndAnnotation: (NSNotification*)notification
+- (void)handleOpenURLWithApplicationSourceAndAnnotation:(NSNotification*)notification
 {
 
     // override to handle urls sent to your app

CordovaLib/CordovaLib.docc/CordovaLib.md

@@ -37,6 +37,7 @@ For more information about Apache Cordova, visit [https://cordova.apache.org](ht
 
 - ``CDVPlugin``
 - ``CDVPluginSchemeHandler``
+- ``CDVPluginAuthenticationHandler``
 
 ### Plugin communication
 - ``CDVPluginResult``

CordovaLib/CordovaLib.docc/upgrading-8.md

@@ -259,6 +259,9 @@ The following headers are deprecated due to adding global category extensions to
   * The ``CDVPluginHandleOpenURLWithAppSourceAndAnnotationNotification`` notification is now deprecated.  
     The existing ``CDVPluginHandleOpenURLNotification`` notification now includes the source and annotation in its `userInfo` dictionary.
 
+* ``CDVPluginAuthenticationHandler``
+  * Newly added protocol for plugins wishing to handle server authentication requests.
+
 * ``CDVPluginSchemeHandler``
   * Newly added protocol for plugins wishing to override WebKit scheme handling for web requests.
 

CordovaLib/include/Cordova/CDVPlugin.h

@@ -40,6 +40,8 @@
 @end
 #endif
 
+NS_ASSUME_NONNULL_BEGIN
+
 extern const NSNotificationName CDVPageDidLoadNotification;
 extern const NSNotificationName CDVPluginHandleOpenURLNotification;
 extern const NSNotificationName CDVPluginHandleOpenURLWithAppSourceAndAnnotationNotification CDV_DEPRECATED(8, "Find sourceApplication and annotations in the userInfo of the CDVPluginHandleOpenURLNotification notification.");
@@ -85,6 +87,41 @@ extern const NSNotificationName CDVViewWillTransitionToSizeNotification;
 
 #pragma mark - Plugin protocols
 
+/**
+ A protocol for Cordova plugins to intercept and respond to server
+ authentication challenges through WebKit.
+
+ Your plugin should implement this protocol and the
+ ``willHandleAuthenticationChallenge:completionHandler:`` method to return
+ `YES` if it wants to support responses to server-side authentication
+ challenges, otherwise the default NSURLSession handling for authentication
+ challenges will be used.
+ */
+@protocol CDVPluginAuthenticationHandler <NSObject>
+
+/**
+ Asks your plugin to respond to an authentication challenge.
+
+ Return `YES` if the plugin is handling the challenge, and `NO` to fallback to
+ the default handling.
+
+ - Parameters:
+   - challenge: The authentication challenge.
+   - completionHandler: A completion handler block to execute with the response.
+     This handler has no return value and takes the following parameters:
+     - disposition: The option to use to handle the challenge. For a list of
+       options, see `NSURLSessionAuthChallengeDisposition`.
+     - credential: The credential to use for authentication when the
+       `disposition` parameter contains the value
+       `NSURLSessionAuthChallengeUseCredential`. Specify `nil` to continue
+       without a credential.
+ - Returns: A Boolean value indicating if the plugin is handling the request.
+ */
+- (BOOL)willHandleAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential * _Nullable))completionHandler;
+
+@end
+
+
 /**
  A protocol for Cordova plugins to intercept handling of WebKit resource
  loading for a custom URL scheme.
@@ -128,3 +165,5 @@ extern const NSNotificationName CDVViewWillTransitionToSizeNotification;
  */
 - (void)stopSchemeTask:(id <WKURLSchemeTask>)task;
 @end
+
+NS_ASSUME_NONNULL_END