feat(ios): device client-cert mTLS — ClientTLS package, transport wiring, install UX (C-iOS)

- ios/Packages/ClientTLS: SecIdentity wrapper, PKCS12 importer (typed errors), keychain store
  (AfterFirstUnlockThisDeviceOnly), pure MutualTLSChallengeResponder truth table, cross-platform
  X.509 DER summary. 14/14 tests.
- Both transports (SessionCore URLSessionTermTransport, App URLSessionHTTPTransport) + SessionThumbnail
  take a lazy @Sendable ()->ClientIdentity? provider: WS resolves per-connect, HTTP per client-cert
  challenge, so a freshly-imported cert applies without an app relaunch. AppEnvironment injects
  { store.loadedIdentityOrNil() }.
- ClientCertScreen (.fileImporter([.pkcs12]) + passphrase -> import -> keychain), reachable via a
  设备证书 entry in SessionListScreen.hostMenu. PairingViewModel gates tunnel-host probes on cert
  presence and re-maps mTLS-reject to a clientCertRejected message.
Verified: ClientTLS 14/14, SessionCore 93/93, xcodegen + xcodebuild BUILD SUCCEEDED.
This commit is contained in:
Yaojia Wang
2026-07-07 09:42:12 +02:00
parent 5337281e85
commit e38e6d1689
25 changed files with 1510 additions and 30 deletions

View File

@@ -1,3 +1,4 @@
import ClientTLS
import Foundation
import WireProtocol
@@ -9,14 +10,39 @@ import WireProtocol
/// bypass that single audited point (review CRITICAL).
struct URLSessionHTTPTransport: HTTPTransport {
private let session: URLSession
/// Strong reference to the mTLS delegate. URLSession retains its delegate
/// until invalidated, but this ephemeral session is never explicitly
/// invalidated, so holding it here documents the ownership and keeps the
/// transport a self-contained value.
private let tlsDelegate: LazyClientTLSSessionDelegate
/// Default is EPHEMERAL, not `.shared` (T-iOS-19 finding): RO GET bodies
/// include `/live-sessions/:id/preview` raw terminal ring-buffer bytes
/// that may contain printed secrets and `.shared`'s default URLCache
/// writes responses to disk. Ephemeral keeps them memory-only, matching
/// the WS transport and the privacy-shade posture.
init(session: URLSession = URLSession(configuration: .ephemeral)) {
self.session = session
/// Fixed-identity convenience (snapshot callers / tests): wraps a constant
/// provider, so behaviour is identical to capturing the identity directly.
init(identity: ClientIdentity? = nil) {
self.init(identityProvider: { identity })
}
/// C-iOS-2 (MEDIUM no-relaunch fix) · The session's mTLS delegate resolves
/// the device identity LAZILY, per client-certificate challenge, from
/// `identityProvider`. A `ClientCertificate` challenge from a tunneled host
/// is thus answered with whatever cert is installed AT CHALLENGE TIME so a
/// certificate imported mid-run is presented on the NEXT TLS handshake
/// without an app relaunch (a snapshot captured here would stay stale). The
/// session itself stays a single long-lived value (no per-request churn).
/// Local http/https hosts never issue that challenge, so the provider is
/// never even consulted for them (and a `nil` result is inert regardless).
///
/// EPHEMERAL, not `.shared` (T-iOS-19 finding): RO GET bodies include
/// `/live-sessions/:id/preview` raw terminal ring-buffer bytes that may
/// contain printed secrets and `.shared`'s default URLCache writes
/// responses to disk. Ephemeral keeps them memory-only, matching the WS
/// transport and the privacy-shade posture.
init(identityProvider: @escaping @Sendable () -> ClientIdentity?) {
let delegate = LazyClientTLSSessionDelegate(identityProvider: identityProvider)
self.tlsDelegate = delegate
self.session = URLSession(
configuration: .ephemeral, delegate: delegate, delegateQueue: nil
)
}
func send(_ request: URLRequest) async throws -> (Data, HTTPURLResponse) {
@@ -29,3 +55,40 @@ struct URLSessionHTTPTransport: HTTPTransport {
return (data, httpResponse)
}
}
/// C-iOS-2 (MEDIUM no-relaunch fix) · Session-level mTLS delegate that resolves
/// the device identity FRESH per client-certificate challenge the App-layer
/// twin of ClientTLS's fixed-identity `ClientTLSSessionDelegate` (which captures
/// the identity once). The provider is only consulted for a `ClientCertificate`
/// challenge, so a `ServerTrust` challenge never triggers a keychain read; the
/// pure decision itself is delegated to the shared `MutualTLSChallengeResponder`
/// (single truth table, unit-tested in ClientTLS).
///
/// `@unchecked Sendable`: URLSession retains its delegate and invokes it from
/// arbitrary queues; every stored field is an immutable `let` over a `@Sendable`
/// value (the provider is `@Sendable`, the responder is stateless).
private final class LazyClientTLSSessionDelegate:
NSObject, URLSessionDelegate, @unchecked Sendable {
private let identityProvider: @Sendable () -> ClientIdentity?
private let responder = MutualTLSChallengeResponder()
init(identityProvider: @escaping @Sendable () -> ClientIdentity?) {
self.identityProvider = identityProvider
super.init()
}
func urlSession(
_ session: URLSession,
didReceive challenge: URLAuthenticationChallenge,
completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
) {
// Only a client-certificate challenge needs the identity; resolving it
// for a server-trust challenge would do a needless keychain read/import
// on every HTTPS handshake.
let isClientCert = challenge.protectionSpace.authenticationMethod
== NSURLAuthenticationMethodClientCertificate
let identity = isClientCert ? identityProvider() : nil
let resolution = responder.resolve(challenge, identity: identity)
completionHandler(resolution.disposition, resolution.credential)
}
}