SPKI Pinning support for Network.framework-backed connections

[o-nnerb]

Summary

SPKIPinning (this repo's wrapper around async-http-client's native SPKI pinning) does not work
when a session uses Network.framework — Session().enableNetworkFramework(). This isn't a gap in
RequestDL; it's a deliberate, documented limitation in async-http-client itself, and RequestDL
currently works around it by silently downgrading the transport rather than actually supporting the
combination.

The gap

async-http-client's HTTPConnectionPool+Factory.swift, in the Network.framework connection path,
hard-fails as soon as pinning is configured:

if tlsPinning != nil {
    throw SPKIPinningHandlerError.networkFrameworkNotSupported
}

The reason is structural, not a missing if: SPKIPinningHandler is a NIO ChannelInboundHandler
that reads the peer certificate off NIOSSLHandler once the TLS handshake completes. When
Network.framework performs the handshake itself (NWConnection, outside NIO's channel pipeline),
there is no NIOSSLHandler for it to attach to — the handler has nothing to read.

RequestDL's Internals.SecureConnection.isCompatibleWithNetworkFramework already treats any session
with SPKIPinning configured as incompatible with Network.framework, and steers it onto
MultiThreadedEventLoopGroup instead of NIOTSEventLoopGroup — avoiding the runtime crash, but at
the cost of silently losing Network.framework's benefits (VPN awareness, constrained/expensive-path
integration, multipath) for any session that also wants pinning. That's a library-level workaround,
not a fix; a wrapper library can only choose which transport a session uses, it cannot make pinning
work on the Network.framework transport, because the hook to do that doesn't exist outside
async-http-client.

Why there's a real path forward

async-http-client already has the right kind of hook for this, and already uses it for a similar
purpose: TLSConfiguration+NIOTransportServices.swift's getNWProtocolTLSOptions installs a
sec_protocol_options_set_verify_block whenever custom trust roots or non-default certificate
verification is configured. That's Apple's own public API for custom certificate verification under
Network.framework — the same shape of problem as SPKI pin checking (given the SecTrust handed to
the verify block, extract the leaf certificate's public key and compare its hash against a known
set). Nothing about that requires a NIO pipeline.

Proposed change (full detail in a companion design doc kept alongside RequestDL's fork of
async-http-client):

1. Thread an optional SPKIPinningConfiguration into getNWProtocolTLSOptions.
2. Extend the verify block to validate the leaf certificate's SPKI hash the same way
   SPKIPinningHandler does today, using SecTrust/SecCertificate APIs instead of
   NIOSSLCertificate.extractPublicKey().
3. Respect SPKIPinningPolicy (.audit vs .strict) identically to the NIOSSL path.
4. Remove the networkFrameworkNotSupported throw once the verify-block path exists and is tested.
5. Update SPKIPinningConfiguration's doc comments to drop the Network.framework caveat.

One open question to resolve during implementation: SecTrustCopyKey (the most direct extraction
API) requires macOS 11+/iOS 14+, while SPKIPinningHandler itself is gated at macOS 10.15/iOS 13
today — whether the Network.framework path needs a narrower availability window or an older
SecCertificateCopyKey fallback isn't resolved yet.

Out of scope

• Non-Darwin platforms (no Network.framework there; unaffected).
• Proxied connections (already supported today regardless of transport, since pinning validates the
  origin's TLS, not the tunnel).
• Any change to pin format or policy semantics — this only extends where the existing validation
  can run.

Status

This has to land in swift-server/async-http-client — RequestDL cannot implement it as a wrapper.
Milestone: TBD, pending that upstream work and a released version including it. Once available,
RequestDL's Internals.SecureConnection.isCompatibleWithNetworkFramework workaround can be retired
and SPKIPinning + enableNetworkFramework() can be used together.

[o-nnerb]

Fechando esta discussion — foi criada por engano.

O pedido original era documentar como Feature Proposal as mudanças de SPKI Pinning já implementadas na branch tls-pinning deste repo, tendo como dependência o swift-server/async-http-client#910 (ainda não mergeada upstream). Interpretei errado e investiguei um problema diferente (Network.framework).

Além de não ser o que foi pedido, o conteúdo também não procede como "gap a corrigir": a própria PR #910 já documenta isso como requisito de design deliberado — "Requires OpenSSL/BoringSSL backend (Network.framework connections ignore pinning configuration)" — não uma limitação a ser removida depois.

Proposta correta sendo publicada em seguida.