Add support for specifying a custom client certificate verification callback

Motivation:
`NIOSSL` supports specifying a custom verification callback for client certificate verification. When such a callback is provided to `NIOSSLServerHandler`, it will use the callback to _replace_ its default client certificate verification logic, and surface the peer's validated chain of trust (derived and returned from the custom callback). This can be useful for mTLS implementations.

`NIOHTTPServer` currently does not support propagating a custom verification callback to `NIOSSLServerHandler`. This change adds support for that and also surfaces the peer's validated certificate chain that then becomes available as a result.

Modifications:
- Updated `HTTPServerConfiguration` to also include a `customCertificateVerificationCallback` argument for the `mTLS` and `reloadingMTLS` cases of `TransportSecurity`.
  - Note: This exposes `NIO` types at the `HTTPServerConfiguration` level (in particular, the arguments of the callback are [`NIOSSLCertificate`] and an `EventLoopPromise` that must be fulfilled within the callback). We currently do not have a `NIOHTTPServer`-specific configuration, so let us discuss in the comments what the best way to allow users to specify a custom verification callback would be.
- Updated the `serveSecureUpgrade` method in `NIOHTTPServer` to (1) propagate the custom verification callback into the underlying `NIOSSLServerHandler`, (2) extract the peer certificate chain `EventLoopFuture` per connection, and expose that future in a new type in `NIOHTTPServer` named `Context`.
  - The `Context` type is accessed from a task-local property `context`. Users can await the result of the promise from their route handlers by calling `NIOHTTPServer.context.peerCertificateChain()`.
  - The name of this type, its properties, the task-local approach, etc. are all very much open for discussion.
- Added end-to-end tests for this functionality for both HTTP/1.1 and HTTP2.
- Other changes:
  - Added `NIOSSL+X509` containing some convenience conversions between `NIOSSL` and `X509` types.
  - Added documentation to the `TransportSecurity` methods as they were missing.

Result:
Users can now specify a custom verification callback and access the peer's validated certificate chain from the request handler.

Author: aryan-25

Package.swift

@@ -24,7 +24,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.4"),
         .package(url: "https://github.com/apple/swift-http-types.git", from: "1.0.0"),
         .package(url: "https://github.com/apple/swift-distributed-tracing.git", from: "1.0.0"),
-        .package(url: "https://github.com/apple/swift-certificates.git", from: "1.0.4"),
+        .package(url: "https://github.com/apple/swift-certificates.git", from: "1.16.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"),
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
         .package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.0.0"),

Sources/HTTPServer/HTTPServerConfiguration.swift

@@ -11,9 +11,10 @@
 //
 //===----------------------------------------------------------------------===//
 
-public import X509
 public import NIOCertificateReloading
-import NIOSSL
+public import NIOCore
+public import NIOSSL
+public import X509
 
 /// Configuration settings for the HTTP server.
 ///
@@ -53,6 +54,26 @@ public struct HTTPServerConfiguration: Sendable {
     /// Provides options for running the server with or without TLS encryption.
     /// When using TLS, you must either provide a certificate chain and private key, or a `CertificateReloader`.
     public struct TransportSecurity: Sendable {
+        /// A callback that replaces `NIOSSL`'s default certificate verification with custom verification logic.
+        ///
+        /// This is just a `Sendable` version of `NIOSSLCustomVerificationCallbackWithMetadata`.
+        ///
+        /// ## Usage
+        ///
+        /// The callback receives:
+        /// - **certificates**: The certificates presented by the peer. You are responsible for building and validating
+        ///   a chain of trust from these certificates.
+        /// - **promise**: A promise that must be completed. Call `promise.succeed(...)` with the subset of certificates
+        ///   that formed the validated chain of trust, or `promise.fail()` if verification fails.
+        ///
+        /// - Warning: This callback completely replaces NIOSSL's certificate verification logic and must be used with
+        ///   caution.
+        public typealias CustomCertificateVerificationCallback =
+            @Sendable (
+                [NIOSSLCertificate],
+                EventLoopPromise<NIOSSLVerificationResultWithMetadata>
+            ) -> Void
+
         enum Backing {
             case plaintext
             case tls(
@@ -63,18 +84,24 @@ public struct HTTPServerConfiguration: Sendable {
             case mTLS(
                 certificateChain: [Certificate],
                 privateKey: Certificate.PrivateKey,
-                trustRoots: [Certificate]?
+                trustRoots: [Certificate]?,
+                customCertificateVerificationCallback: CustomCertificateVerificationCallback? = nil
             )
             case reloadingMTLS(
                 certificateReloader: any CertificateReloader,
-                trustRoots: [Certificate]?
+                trustRoots: [Certificate]?,
+                customCertificateVerificationCallback: CustomCertificateVerificationCallback? = nil
             )
         }
 
         let backing: Backing
 
         public static let plaintext: Self = Self(backing: .plaintext)
 
+        /// Enables TLS.
+        /// - Parameters:
+        ///   - certificateChain: The certificate chain to present during negotiation.
+        ///   - privateKey: The private key corresponding to the leaf certificate in `certificateChain`.
         public static func tls(
             certificateChain: [Certificate],
             privateKey: Certificate.PrivateKey
@@ -87,32 +114,60 @@ public struct HTTPServerConfiguration: Sendable {
             )
         }
 
+        /// Enables TLS with automatic certificate reloading.
+        /// - Parameters:
+        ///   - certificateReloader: The certificate reloader instance.
         public static func tls(certificateReloader: any CertificateReloader) throws -> Self {
             Self(backing: .reloadingTLS(certificateReloader: certificateReloader))
         }
 
+        /// Enables mTLS. Optionally provide a custom verification callback to override the default verification logic
+        /// used to verify client certificates, and control the derivation of a validated chain of trust from the
+        /// certificates presented by the peer.
+        ///
+        /// - Parameters:
+        ///   - certificateChain: The certificate chain to present during negotiation.
+        ///   - privateKey: The private key corresponding to the leaf certificate in `certificateChain`.
+        ///   - trustRoots: The root certificates to trust when verifying client certificates.
+        ///   - customCertificateVerificationCallback: A custom certificate verification callback. This will override
+        ///     NIOSSL's default certificate verification logic.
         public static func mTLS(
             certificateChain: [Certificate],
             privateKey: Certificate.PrivateKey,
-            trustRoots: [Certificate]?
+            trustRoots: [Certificate]?,
+            customCertificateVerificationCallback: CustomCertificateVerificationCallback? = nil
         ) -> Self {
             Self(
                 backing: .mTLS(
                     certificateChain: certificateChain,
                     privateKey: privateKey,
-                    trustRoots: trustRoots
+                    trustRoots: trustRoots,
+                    customCertificateVerificationCallback: customCertificateVerificationCallback
                 )
             )
         }
 
+        /// Enables mTLS with certificate reloading. Optionally provide a custom verification callback to override the default verification logic
+        /// used to verify client certificates, and control the derivation of a validated chain of trust from the
+        /// certificates presented by the peer.
+        ///
+        /// - Parameters:
+        ///   - certificateReloader: The certificate reloader instance.
+        ///   - trustRoots: The root certificates to trust when verifying client certificates.
+        ///   - customCertificateVerificationCallback: A custom certificate verification callback. This will override
+        ///     NIOSSL's default certificate verification logic.
         public static func mTLS(
             certificateReloader: any CertificateReloader,
-            trustRoots: [Certificate]?
+            trustRoots: [Certificate]?,
+            customCertificateVerificationCallback: CustomCertificateVerificationCallback? = nil
         ) throws -> Self {
-            Self(backing: .reloadingMTLS(
-                certificateReloader: certificateReloader,
-                trustRoots: trustRoots
-            ))
+            Self(
+                backing: .reloadingMTLS(
+                    certificateReloader: certificateReloader,
+                    trustRoots: trustRoots,
+                    customCertificateVerificationCallback: customCertificateVerificationCallback
+                )
+            )
         }
     }
 
@@ -148,7 +203,7 @@ public struct HTTPServerConfiguration: Sendable {
                 maxConcurrentStreams: nil
             )
         }
-     }
+    }
 
     /// Configuration for the backpressure strategy to use when reading requests and writing back responses.
     public struct BackPressureStrategy: Sendable {
@@ -187,7 +242,7 @@ public struct HTTPServerConfiguration: Sendable {
     /// Create a new configuration.
     /// - Parameters:
     ///   - bindTarget: A ``BindTarget``.
-    ///   - tlsConfiguration: A ``TLSConfiguration``. Defaults to ``TLSConfiguration/insecure``.
+    ///   - transportSecurity: A ``TransportSecurity``. Defaults to ``TransportSecurity/plaintext``.
     ///   - backpressureStrategy: A ``BackPressureStrategy``.
     ///   Defaults to ``BackPressureStrategy/watermark(low:high:)`` with a low watermark of 2 and a high of 10.
     ///   - http2: A ``HTTP2``. Defaults to ``HTTP2/defaults``.