feat(apple/library): mTLS — authenticate by the paired identity, drop the token

Phase 3: the Apple library now talks to the host's HTTPS mgmt API (b4a85a8) over mTLS
using this client's persistent identity — the SAME cert the host paired over QUIC — so
there is NO manual token anymore.

- ClientTLS: builds a SecIdentity from the stored PEM (CryptoKit parses the rcgen P-256
  PKCS#8 key → x963 → SecKey; the cert PEM → SecCertificate; SecIdentityCreateWithCertificate
  pairs them via the Keychain). macOS-only for now (that API is unavailable on iOS — a
  PKCS#12 path would be needed there; the client is macOS-first).
- LibraryTLSDelegate: pins the host's self-signed cert by the fingerprint the client
  already trusts, and presents the identity for the client-cert challenge.
- LibraryClient.fetch now does GET https://…/library with the identity + host fingerprint;
  the whole connection form (port + token) and StoredHost.mgmtToken/setMgmt are gone — the
  library "just works" for a paired host. 401 → "pair with the host first".

Can't compile Swift on the Linux box; CI (apple.yml) compiles the macOS path incl. the
Security/CryptoKit code. Runtime (SecIdentity build + the mTLS handshake) needs Mac
validation. Pairs with the host mTLS already landed + live-tested.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/apple/Sources/PunktfunkKit/ClientTLS.swift

@@ -0,0 +1,142 @@
+// mTLS for the management REST API. The host now serves the API over HTTPS and authorizes a
+// request whose client certificate is in its paired store (host commit b4a85a8) — the SAME
+// identity + trust the QUIC data plane uses — so a paired client needs no bearer token.
+//
+// To present that identity, URLSession needs a SecIdentity (cert + private key pair). The client
+// stores its identity as PEM (rcgen ECDSA P-256, PKCS#8 key). We rebuild a SecIdentity natively:
+// CryptoKit parses the key → its X9.63 form → a SecKey, the cert PEM → a SecCertificate, and
+// SecIdentityCreateWithCertificate pairs them via the Keychain. This is macOS-only
+// (SecIdentityCreateWithCertificate is unavailable on iOS — that path will need a PKCS#12); the
+// client library is macOS-first today.
+
+import CryptoKit
+import Foundation
+import Security
+import os
+
+private let tlsLog = Logger(subsystem: "io.unom.punktfunk", category: "library-tls")
+
+enum ClientTLS {
+    enum TLSError: LocalizedError {
+        case unsupportedPlatform
+        case badKey(String)
+        case badCert
+        case identity(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .unsupportedPlatform:
+                return "Library mTLS is supported on macOS only right now."
+            case .badKey(let why): return "Couldn't load the client key: \(why)"
+            case .badCert: return "Couldn't load the client certificate."
+            case .identity(let why): return "Couldn't build the client identity: \(why)"
+            }
+        }
+    }
+
+    /// First PEM block of `type` ("CERTIFICATE" / "PRIVATE KEY") → its DER bytes.
+    private static func derFromPEM(_ pem: String, type: String) -> Data? {
+        guard let start = pem.range(of: "-----BEGIN \(type)-----"),
+              let end = pem.range(of: "-----END \(type)-----", range: start.upperBound..<pem.endIndex)
+        else { return nil }
+        let b64 = pem[start.upperBound..<end.lowerBound]
+            .components(separatedBy: .whitespacesAndNewlines).joined()
+        return Data(base64Encoded: b64)
+    }
+
+    /// Build a `SecIdentity` from the client's PEM cert + PKCS#8 P-256 key. Pairs them via the
+    /// Keychain (the key is stored once under a stable tag, so repeat calls reuse it).
+    static func makeIdentity(certPEM: String, keyPEM: String) throws -> SecIdentity {
+        #if os(macOS)
+        // Key: CryptoKit accepts the SEC1 or PKCS#8 PEM; its x963 form is what SecKey wants.
+        let priv: P256.Signing.PrivateKey
+        do {
+            priv = try P256.Signing.PrivateKey(pemRepresentation: keyPEM)
+        } catch {
+            throw TLSError.badKey(error.localizedDescription)
+        }
+        var keyError: Unmanaged<CFError>?
+        let attrs: [CFString: Any] = [
+            kSecAttrKeyType: kSecAttrKeyTypeECSECPrimeRandom,
+            kSecAttrKeyClass: kSecAttrKeyClassPrivate,
+            kSecAttrKeySizeInBits: 256,
+        ]
+        guard let secKey = SecKeyCreateWithData(
+            priv.x963Representation as CFData, attrs as CFDictionary, &keyError)
+        else {
+            throw TLSError.badKey((keyError?.takeRetainedValue()).map { "\($0)" } ?? "SecKeyCreateWithData")
+        }
+
+        guard let certDER = derFromPEM(certPEM, type: "CERTIFICATE"),
+              let cert = SecCertificateCreateWithData(nil, certDER as CFData)
+        else { throw TLSError.badCert }
+
+        // The key must live in a Keychain for SecIdentityCreateWithCertificate to pair it with the
+        // cert. Add it under a stable tag; a duplicate just means a previous fetch already did.
+        let tag = Data("io.unom.punktfunk.library-client-key".utf8)
+        let add: [CFString: Any] = [
+            kSecClass: kSecClassKey,
+            kSecAttrApplicationTag: tag,
+            kSecValueRef: secKey,
+        ]
+        let status = SecItemAdd(add as CFDictionary, nil)
+        guard status == errSecSuccess || status == errSecDuplicateItem else {
+            throw TLSError.identity("keychain add failed (OSStatus \(status))")
+        }
+
+        var identity: SecIdentity?
+        let idStatus = SecIdentityCreateWithCertificate(nil, cert, &identity)
+        guard idStatus == errSecSuccess, let identity else {
+            throw TLSError.identity("SecIdentityCreateWithCertificate (OSStatus \(idStatus))")
+        }
+        return identity
+        #else
+        throw TLSError.unsupportedPlatform
+        #endif
+    }
+}
+
+/// URLSession delegate that pins the host's self-signed cert (by the fingerprint the client
+/// already trusts) and presents the client identity for the mTLS client-cert challenge.
+final class LibraryTLSDelegate: NSObject, URLSessionDelegate {
+    private let identity: SecIdentity
+    private let pinnedHostFingerprint: Data? // SHA-256 of the host cert DER; nil = accept any (TOFU)
+
+    init(identity: SecIdentity, pinnedHostFingerprint: Data?) {
+        self.identity = identity
+        self.pinnedHostFingerprint = pinnedHostFingerprint
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge,
+        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
+    ) {
+        switch challenge.protectionSpace.authenticationMethod {
+        case NSURLAuthenticationMethodServerTrust:
+            // Pin the host cert by fingerprint — the host is self-signed (the client trusts it the
+            // same way the QUIC session does). No pin yet (TOFU) → accept the presented leaf.
+            guard let trust = challenge.protectionSpace.serverTrust,
+                  let leaf = (SecTrustCopyCertificateChain(trust) as? [SecCertificate])?.first
+            else {
+                completionHandler(.cancelAuthenticationChallenge, nil)
+                return
+            }
+            let der = SecCertificateCopyData(leaf) as Data
+            let fp = Data(SHA256.hash(data: der))
+            if let pinned = pinnedHostFingerprint, pinned != fp {
+                tlsLog.warning("library: host cert fingerprint mismatch — refusing")
+                completionHandler(.cancelAuthenticationChallenge, nil)
+                return
+            }
+            completionHandler(.useCredential, URLCredential(trust: trust))
+
+        case NSURLAuthenticationMethodClientCertificate:
+            completionHandler(.useCredential,
+                URLCredential(identity: identity, certificates: nil, persistence: .forSession))
+
+        default:
+            completionHandler(.performDefaultHandling, nil)
+        }
+    }
+}