From 78a02bc99469df2cc9b9223fca463ac4b9d4d363 Mon Sep 17 00:00:00 2001
From: enricobuehler <buehler@unom.io>
Date: Thu, 6 Aug 2026 01:43:19 +0200
Subject: [PATCH 1/4] fix(apple): ATS blocked the library on every non-RFC1918
 host

The game library rides the management REST API over HTTPS (TCP 47990) through
URLSession, authenticated by mTLS and pinned by SHA-256 fingerprint. The app
declared no App Transport Security policy at all, so it ran under default ATS --
which exempts only "local" destinations (.local, unqualified names, RFC1918 and
link-local literals) and applies the full policy everywhere else. The host
certificate is self-signed (and carries no SubjectAltName), so it cannot satisfy
that policy: the library loaded at 192.168.x and failed at the TLS layer on any
other address.

Field-reported against a Tailscale host. 100.64.0.0/10 is CGNAT, not RFC1918, so
the library failed there while streaming to the very same address worked -- the
QUIC stream plane is raw UDP and never enters the URL loading system. A WireGuard
peer or a public-IP host breaks identically.

Declares NSAllowsArbitraryLoads, which must stay the dict's only key: iOS 10+ and
macOS 10.12+ ignore it whenever a more granular ATS key sits alongside it. Trust
is unchanged -- LibraryTLSDelegate still pins the host by fingerprint and hands
every other origin (cover-art CDNs) to full system trust evaluation.
---
 clients/apple/Config/Info.plist | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/clients/apple/Config/Info.plist b/clients/apple/Config/Info.plist
index 93224825..898d3e9c 100644
--- a/clients/apple/Config/Info.plist
+++ b/clients/apple/Config/Info.plist
@@ -19,6 +19,25 @@
 	<array>
 		<string>_punktfunk._udp</string>
 	</array>
+	<!-- App Transport Security. We talk to the user's OWN host over HTTPS with a SELF-SIGNED
+	     certificate at a user-supplied address, and verify it by SHA-256 fingerprint pinning
+	     established during PIN pairing (LibraryTLSDelegate) — for a box on someone's LAN there is
+	     no CA that could vouch for it, so pinning is the stronger check, not a weaker one.
+	     Default ATS exempts only "local" destinations (.local, unqualified names, RFC1918 and
+	     link-local literals). Every other address gets the full policy, which a self-signed cert
+	     cannot satisfy — so the management API (game library) worked at 192.168.x but died at the
+	     TLS layer on Tailscale's 100.64/10 CGNAT range, a WireGuard peer, or a public IP. The QUIC
+	     stream plane never showed it: that is raw UDP and never enters the URL loading system.
+	     ⚠ This must stay the ONLY key in this dict. On iOS 10+/macOS 10.12+ the system IGNORES
+	     NSAllowsArbitraryLoads whenever NSAllowsLocalNetworking, NSAllowsArbitraryLoadsInWebContent
+	     or NSAllowsArbitraryLoadsForMedia is present alongside it — adding one silently restores
+	     the bug. Other origins (cover-art CDNs) keep full system trust evaluation regardless:
+	     LibraryTLSDelegate hands every non-host challenge to .performDefaultHandling. -->
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoads</key>
+		<true/>
+	</dict>
 	<!-- Background keep-alive (opt-in, iOS/iPadOS): the ONLY sanctioned way to keep the long-lived
 	     QUIC socket + pump-thread set alive while backgrounded is the audio background mode, backed
 	     by the session's real, audible remote audio (AVAudioEngine keeps rendering). Video decode is

From bae8742e488103e0ab29fdaa6739af1a762a2746 Mon Sep 17 00:00:00 2001
From: enricobuehler <buehler@unom.io>
Date: Thu, 6 Aug 2026 01:56:42 +0200
Subject: [PATCH 2/4] fix(apple): the library's unreachable message pointed at
 the wrong layer

It led with `--mgmt-bind 127.0.0.1`, a rare cause, and never mentioned the one
fact that actually explains the symptom: the library rides the management API on
a different port (47990) than the QUIC stream plane (9777), so it can fail while
streaming to the same host works. Field triage of exactly that case spent hours
on the stream path before anyone questioned the port.

Leads with that now, and names browser-testing the port as the fast split between
"unreachable" and anything client-side.
---
 .../PunktfunkKit/Connection/LibraryClient.swift     | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
index b7024989..e8460fcf 100644
--- a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
+++ b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
@@ -94,9 +94,16 @@ public enum LibraryError: LocalizedError {
         case .http(let code):
             return "The management API returned HTTP \(code)."
         case .unreachable(let why):
-            return "Couldn't reach the host's management API: \(why). It binds the LAN by default, "
-                + "so check the host is updated and reachable (a host pinned to "
-                + "`--mgmt-bind 127.0.0.1` is loopback-only and can't be browsed remotely)."
+            // The library rides a DIFFERENT port than the stream (the management API, 47990 by
+            // default; the stream is QUIC on 9777), so it can fail while streaming to the same
+            // host works perfectly — say that first, because the opposite assumption has sent
+            // more than one person hunting the wrong layer. Opening that URL in a browser is the
+            // fastest way to tell "port unreachable" apart from anything client-side.
+            return "Couldn't reach the host's management API: \(why). The library uses a "
+                + "different port than the stream (47990 by default), so streaming can work "
+                + "while this doesn't. Check that port is reachable from this device, and that "
+                + "the host isn't pinned to `--mgmt-bind 127.0.0.1`, which serves it to the "
+                + "host itself only."
         }
     }
 }

From 244cafe00554f03bd0085bcaaeb962bfa60ca7a4 Mon Sep 17 00:00:00 2001
From: enricobuehler <buehler@unom.io>
Date: Thu, 6 Aug 2026 02:08:23 +0200
Subject: [PATCH 3/4] refactor(apple): move the mgmt API off URLSession so ATS
 can stay on

The previous commit bought the library back on VPN/remote hosts by declaring
NSAllowsArbitraryLoads, which works but is blunt: it drops ATS for ALL of the
app's URLSession traffic, and the only other traffic is third-party cover-art
CDN fetches -- the one surface we never wanted to open. It cost the TLS-version
floor, forward secrecy, and the cleartext-HTTP block on URLs the host supplies
at runtime (custom entries and scanner plugins carry arbitrary ones).

So take the host out of the URL loading system instead. MgmtTransport speaks
HTTPS over Network.framework, which ATS does not govern, and states the trust
rule we actually mean in a verify block: the leaf must hash to the fingerprint
pinned during PIN pairing. That is the same rule punktfunk-core has always
applied on the QUIC stream plane -- which is exactly why streaming kept working
over Tailscale while the library did not.

With that, the ATS dict is gone and ATS is fully enforced again. Cover-art CDN
fetches keep ordinary URLSession with full system trust evaluation and no client
certificate. LibraryTLSDelegate is deleted; nothing pins through URLSession now.

Also here:
- HTTPResponse: just enough HTTP/1.1 to read one GET -- status, headers,
  Content-Length and chunked framing (hyper streams the art proxy chunked). A
  body shorter than Content-Length throws instead of returning partial JSON,
  which would otherwise read as "this host has no games".
- LibraryError.pinMismatch, so a re-keyed host says "pair again" rather than
  sending someone to debug their network.
- 403 joins 401 as "unauthorized": both are the host declining the certificate.
- baseURL brackets IPv6 literals; the old string interpolation did not.
- 11 tests covering the framings hyper emits and the failure modes that would
  otherwise be silent.

Known trade-off: no connection reuse yet, so each poster costs its own
handshake where the pooled URLSession shared one. Fine on a LAN, worth revisiting
for large libraries over a high-latency link.
---
 clients/apple/Config/Info.plist               |  27 +--
 .../Home/LibraryCoverflowView.swift           |   4 +-
 .../PunktfunkClient/Home/LibraryView.swift    |  27 +--
 .../PunktfunkClient/Home/LibraryWidgets.swift |   8 +-
 .../PunktfunkKit/Connection/ClientTLS.swift   |  67 +------
 .../Connection/HTTPResponse.swift             | 129 ++++++++++++
 .../Connection/LibraryClient.swift            | 150 +++++++++-----
 .../Connection/MgmtTransport.swift            | 184 ++++++++++++++++++
 .../LibraryClientTests.swift                  |  98 ++++++++++
 9 files changed, 549 insertions(+), 145 deletions(-)
 create mode 100644 clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift
 create mode 100644 clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift

diff --git a/clients/apple/Config/Info.plist b/clients/apple/Config/Info.plist
index 898d3e9c..287533e8 100644
--- a/clients/apple/Config/Info.plist
+++ b/clients/apple/Config/Info.plist
@@ -19,25 +19,14 @@
 	<array>
 		<string>_punktfunk._udp</string>
 	</array>
-	<!-- App Transport Security. We talk to the user's OWN host over HTTPS with a SELF-SIGNED
-	     certificate at a user-supplied address, and verify it by SHA-256 fingerprint pinning
-	     established during PIN pairing (LibraryTLSDelegate) — for a box on someone's LAN there is
-	     no CA that could vouch for it, so pinning is the stronger check, not a weaker one.
-	     Default ATS exempts only "local" destinations (.local, unqualified names, RFC1918 and
-	     link-local literals). Every other address gets the full policy, which a self-signed cert
-	     cannot satisfy — so the management API (game library) worked at 192.168.x but died at the
-	     TLS layer on Tailscale's 100.64/10 CGNAT range, a WireGuard peer, or a public IP. The QUIC
-	     stream plane never showed it: that is raw UDP and never enters the URL loading system.
-	     ⚠ This must stay the ONLY key in this dict. On iOS 10+/macOS 10.12+ the system IGNORES
-	     NSAllowsArbitraryLoads whenever NSAllowsLocalNetworking, NSAllowsArbitraryLoadsInWebContent
-	     or NSAllowsArbitraryLoadsForMedia is present alongside it — adding one silently restores
-	     the bug. Other origins (cover-art CDNs) keep full system trust evaluation regardless:
-	     LibraryTLSDelegate hands every non-host challenge to .performDefaultHandling. -->
-	<key>NSAppTransportSecurity</key>
-	<dict>
-		<key>NSAllowsArbitraryLoads</key>
-		<true/>
-	</dict>
+	<!-- NOTE: there is deliberately NO NSAppTransportSecurity dict here. ATS stays fully ON.
+	     The host is self-signed at a user-supplied address, which default ATS can never accept
+	     (it exempts only .local, unqualified names, and RFC1918/link-local literals — notably NOT
+	     Tailscale's 100.64/10 CGNAT range), so the management API talks over MgmtTransport
+	     (Network.framework), which is outside the URL loading system and pins the host by
+	     SHA-256 fingerprint instead. That leaves cover-art CDN fetches as the app's only
+	     URLSession traffic, and they keep the full ATS policy — which is the whole reason not to
+	     reach for NSAllowsArbitraryLoads here. See MgmtTransport.swift. -->
 	<!-- Background keep-alive (opt-in, iOS/iPadOS): the ONLY sanctioned way to keep the long-lived
 	     QUIC socket + pump-thread set alive while backgrounded is the audio background mode, backed
 	     by the session's real, audible remote audio (AVAudioEngine keeps rendering). Video decode is
diff --git a/clients/apple/Sources/PunktfunkClient/Home/LibraryCoverflowView.swift b/clients/apple/Sources/PunktfunkClient/Home/LibraryCoverflowView.swift
index 509d3fc8..b2fbe2cc 100644
--- a/clients/apple/Sources/PunktfunkClient/Home/LibraryCoverflowView.swift
+++ b/clients/apple/Sources/PunktfunkClient/Home/LibraryCoverflowView.swift
@@ -21,7 +21,7 @@ import GameController
 struct LibraryCoverflowView: View {
     @Environment(\.gamepadInk) private var ink
     let games: [GameEntry]
-    let imageSession: URLSession?
+    let artLoader: LibraryArtLoader?
     var onLaunch: ((String) -> Void)?
     /// Button B (back) — dismisses the library screen. No touch equivalent needed here (the toolbar
     /// Close button already covers that); this is what makes gamepad-only exit possible.
@@ -124,7 +124,7 @@ struct LibraryCoverflowView: View {
         _ game: GameEntry, width: CGFloat, height: CGFloat, entrance: CardEntrance
     ) -> some View {
         PosterImage(
-            candidates: game.art.posterCandidates, title: game.title, session: imageSession,
+            candidates: game.art.posterCandidates, title: game.title, loader: artLoader,
             onLoaded: { artSettled += 1 })
             .frame(width: width, height: height)
             .clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous))
diff --git a/clients/apple/Sources/PunktfunkClient/Home/LibraryView.swift b/clients/apple/Sources/PunktfunkClient/Home/LibraryView.swift
index 13efdf4e..156f599b 100644
--- a/clients/apple/Sources/PunktfunkClient/Home/LibraryView.swift
+++ b/clients/apple/Sources/PunktfunkClient/Home/LibraryView.swift
@@ -24,10 +24,9 @@ struct LibraryView: View {
     @State private var games: [GameEntry] = []
     @State private var loading = false
     @State private var errorText: String?
-    /// Authenticated session for cover-art fetches (the same paired identity + host pinning as the
-    /// list fetch, reused across every poster in the grid). Built alongside `games` in `load()`;
-    /// torn down on disappear since it isn't one-shot like `LibraryClient.fetch`'s own session.
-    @State private var imageSession: URLSession?
+    /// Cover-art loader (the same paired identity + host pinning as the list fetch, reused across
+    /// every poster in the grid). Built alongside `games` in `load()`; dropped on disappear.
+    @State private var artLoader: LibraryArtLoader?
     #if os(iOS) || os(macOS) || os(tvOS)
     // Gamepad-driven browsing — see ContentView's identical gate. With no controller (or the
     // setting off) every platform keeps the plain-grid presentation of this same view.
@@ -62,8 +61,11 @@ struct LibraryView: View {
             }
             .task { await load() }
             .onDisappear {
-                imageSession?.finishTasksAndInvalidate()
-                imageSession = nil
+                // Hand the loader off before clearing it, so its pooled connections are closed
+                // rather than left open on a screen the user has left.
+                let leaving = artLoader
+                artLoader = nil
+                Task { await leaving?.close() }
             }
             #if os(iOS) || os(macOS)
             // B closes the library even before the coverflow exists (loading / error / empty):
@@ -89,7 +91,7 @@ struct LibraryView: View {
         } else {
             if gamepadUIActive {
                 LibraryCoverflowView(
-                    games: games, imageSession: imageSession, onLaunch: onLaunch,
+                    games: games, artLoader: artLoader, onLaunch: onLaunch,
                     onDismiss: { (onClose ?? { dismiss() })() },
                     controllerActive: controllerActive)
             } else {
@@ -124,10 +126,10 @@ struct LibraryView: View {
         LazyVGrid(columns: columns, spacing: 18) {
             ForEach(entries) { game in
                 if let onLaunch {
-                    Button { onLaunch(game.id) } label: { GameCard(game: game, imageSession: imageSession) }
+                    Button { onLaunch(game.id) } label: { GameCard(game: game, artLoader: artLoader) }
                         .buttonStyle(.plain)
                 } else {
-                    GameCard(game: game, imageSession: imageSession)
+                    GameCard(game: game, artLoader: artLoader)
                 }
             }
         }
@@ -206,8 +208,7 @@ struct LibraryView: View {
                 keyPEM: identity.keyPEM,
                 hostFingerprint: current.pinnedSHA256
             ).launchersFirst
-            imageSession?.finishTasksAndInvalidate()
-            imageSession = try LibraryImageLoader.session(
+            artLoader = try LibraryArtLoader(
                 address: current.address,
                 port: current.effectiveMgmtPort,
                 certPEM: identity.certPEM,
@@ -249,11 +250,11 @@ private struct LibraryBackCatcher: View {
 /// (portrait → header → hero) and finally a text placeholder.
 private struct GameCard: View {
     let game: GameEntry
-    let imageSession: URLSession?
+    let artLoader: LibraryArtLoader?
 
     var body: some View {
         VStack(alignment: .leading, spacing: 6) {
-            PosterImage(candidates: game.art.posterCandidates, title: game.title, session: imageSession)
+            PosterImage(candidates: game.art.posterCandidates, title: game.title, loader: artLoader)
                 .aspectRatio(2.0 / 3.0, contentMode: .fit)
                 .frame(maxWidth: .infinity)
                 .clipShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
diff --git a/clients/apple/Sources/PunktfunkClient/Home/LibraryWidgets.swift b/clients/apple/Sources/PunktfunkClient/Home/LibraryWidgets.swift
index 86d577ac..0048da24 100644
--- a/clients/apple/Sources/PunktfunkClient/Home/LibraryWidgets.swift
+++ b/clients/apple/Sources/PunktfunkClient/Home/LibraryWidgets.swift
@@ -60,8 +60,8 @@ private extension Image {
     }
 }
 
-/// Sequentially tries cover-art URLs over `session` (so a paired client can reach the host's own
-/// art proxy, not just public CDNs — see `LibraryImageLoader`), advancing past any that fail to
+/// Sequentially tries cover-art URLs over `loader` (so a paired client can reach the host's own
+/// art proxy, not just public CDNs — see `LibraryArtLoader`), advancing past any that fail to
 /// load, then a placeholder. The loaded image is hard-clipped to fill the card's actual frame
 /// regardless of its own aspect ratio: a portrait capsule fills it as intended, but a fallback
 /// banner (wide hero/header art, used when a title has no portrait capsule) would otherwise report
@@ -70,7 +70,7 @@ private extension Image {
 struct PosterImage: View {
     let candidates: [URL]
     let title: String
-    let session: URLSession?
+    let loader: LibraryArtLoader?
     /// Fires once this poster has settled — art loaded, or every candidate exhausted and the
     /// placeholder is what it will be. The gamepad coverflow waits on a few of these before
     /// playing its entrance, so the cards swing in carrying artwork rather than grey rectangles.
@@ -108,7 +108,7 @@ struct PosterImage: View {
             onLoaded?()
             return
         }
-        guard let session, let data = try? await session.data(from: candidates[index]).0,
+        guard let loader, let data = try? await loader.data(for: candidates[index]),
               let loaded = PlatformImage(data: data)
         else {
             index += 1 // advance to the next candidate (or past the end → placeholder)
diff --git a/clients/apple/Sources/PunktfunkKit/Connection/ClientTLS.swift b/clients/apple/Sources/PunktfunkKit/Connection/ClientTLS.swift
index 28bdc499..e52888ee 100644
--- a/clients/apple/Sources/PunktfunkKit/Connection/ClientTLS.swift
+++ b/clients/apple/Sources/PunktfunkKit/Connection/ClientTLS.swift
@@ -18,9 +18,6 @@
 import CryptoKit
 import Foundation
 import Security
-import os
-
-private let tlsLog = Logger(subsystem: "io.unom.punktfunk", category: "library-tls")
 
 enum ClientTLS {
     enum TLSError: LocalizedError {
@@ -134,62 +131,8 @@ enum ClientTLS {
     }
 }
 
-/// 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 — but ONLY
-/// for challenges from `host`:`port` (the punktfunk host itself). A session built with this
-/// delegate is safe to reuse for OTHER origins too (e.g. a GOG/Heroic/Xbox cover-art CDN): a
-/// non-matching origin falls through to `.performDefaultHandling`, i.e. normal system trust
-/// evaluation and no client cert — exactly what `URLSession.shared` would have done. Without the
-/// host scoping, pinning would reject every external origin's cert (its fingerprint never matches
-/// the host's) and the client identity would leak to servers that didn't ask for it.
-final class LibraryTLSDelegate: NSObject, URLSessionDelegate {
-    private let identity: SecIdentity
-    private let pinnedHostFingerprint: Data? // SHA-256 of the host cert DER; nil = accept any (TOFU)
-    private let host: String
-    private let port: Int
-
-    init(identity: SecIdentity, pinnedHostFingerprint: Data?, host: String, port: UInt16) {
-        self.identity = identity
-        self.pinnedHostFingerprint = pinnedHostFingerprint
-        self.host = host
-        self.port = Int(port)
-    }
-
-    func urlSession(
-        _ session: URLSession,
-        didReceive challenge: URLAuthenticationChallenge,
-        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
-    ) {
-        let space = challenge.protectionSpace
-        guard space.host == host, space.port == port else {
-            completionHandler(.performDefaultHandling, nil)
-            return
-        }
-        switch space.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 = space.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)
-        }
-    }
-}
+// The URLSession pinning delegate that used to live here is gone: the management API now speaks
+// over `MgmtTransport` (Network.framework), which states the same trust rule in a
+// `sec_protocol_options_set_verify_block` and — unlike the URL loading system — is not subject to
+// App Transport Security. That is what lets ATS stay ON for the cover-art CDN fetches, which are
+// the only URLSession traffic left in the app. See MgmtTransport.swift for the full rationale.
diff --git a/clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift b/clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift
new file mode 100644
index 00000000..1c604cd7
--- /dev/null
+++ b/clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift
@@ -0,0 +1,129 @@
+// Minimal HTTP/1.1 response parsing for `MgmtTransport`.
+//
+// We speak HTTP ourselves because the management API has to be reached OUTSIDE the URL loading
+// system: App Transport Security applies to URLSession and cannot be relaxed for the arbitrary,
+// user-supplied addresses a punktfunk host lives at (see MgmtTransport for the full story). What
+// we need is one unauthenticated-by-header GET per request, so this covers exactly that and
+// nothing more — no redirects, no keep-alive, no request bodies, no content negotiation.
+//
+// Deliberately free of any Network.framework / PunktfunkCore dependency: it is pure bytes-in,
+// value-out, so it can be unit-tested (and typechecked) on its own.
+
+import Foundation
+
+/// A parsed HTTP/1.1 response. `headers` keys are lowercased, so lookups are case-insensitive the
+/// way the grammar requires.
+struct HTTPResponse: Sendable {
+    let status: Int
+    let headers: [String: String]
+    let body: Data
+
+    func header(_ name: String) -> String? { headers[name.lowercased()] }
+}
+
+enum HTTPParseError: Error, Sendable {
+    /// The header block never terminated, or the body is shorter than `Content-Length` promised —
+    /// i.e. the peer hung up mid-response. Never surface a truncated body as success: a clipped
+    /// JSON array would read as "this host has no games" rather than as the failure it is.
+    case truncated
+    case malformedStatusLine
+    case malformedHeader
+    case malformedChunk
+}
+
+enum HTTPResponseParser {
+    /// Parse a complete response — everything read from the socket until EOF.
+    static func parse(_ raw: Data) throws -> HTTPResponse {
+        let bytes = [UInt8](raw)
+        guard let headEnd = findHeaderEnd(bytes) else { throw HTTPParseError.truncated }
+        // Header field-values are ISO-8859-1 by the grammar; decoding that way never fails, which
+        // keeps a stray non-UTF-8 byte in some header from failing the whole response.
+        let head = String(decoding: bytes[0..<headEnd], as: UTF8.self)
+        var lines = head.components(separatedBy: "\r\n")
+        guard !lines.isEmpty else { throw HTTPParseError.malformedStatusLine }
+
+        // "HTTP/1.1 200 OK" — the reason phrase is optional and ignored.
+        let statusLine = lines.removeFirst().split(separator: " ", maxSplits: 2,
+                                                   omittingEmptySubsequences: false)
+        guard statusLine.count >= 2, statusLine[0].hasPrefix("HTTP/"),
+              let status = Int(statusLine[1])
+        else { throw HTTPParseError.malformedStatusLine }
+
+        var headers: [String: String] = [:]
+        for line in lines where !line.isEmpty {
+            // A leading space/tab marks an obsolete folded continuation line. Nothing we talk to
+            // emits them, and silently mis-parsing one as a field is worse than refusing it.
+            guard !line.hasPrefix(" "), !line.hasPrefix("\t"),
+                  let colon = line.firstIndex(of: ":")
+            else { throw HTTPParseError.malformedHeader }
+            let name = String(line[line.startIndex..<colon]).lowercased()
+            let value = String(line[line.index(after: colon)...])
+                .trimmingCharacters(in: .whitespaces)
+            // Repeated fields join with ", " per RFC 9110; none of ours repeat, but dropping one
+            // silently would be a lie.
+            headers[name] = headers[name].map { "\($0), \(value)" } ?? value
+        }
+
+        let rest = Data(bytes[(headEnd + 4)...])
+        let body: Data
+        if headers["transfer-encoding"]?.lowercased().contains("chunked") == true {
+            body = try decodeChunked(rest)
+        } else if let lengthField = headers["content-length"] {
+            guard let length = Int(lengthField.trimmingCharacters(in: .whitespaces)), length >= 0
+            else { throw HTTPParseError.malformedHeader }
+            guard rest.count >= length else { throw HTTPParseError.truncated }
+            body = rest.prefix(length)
+        } else {
+            // No framing header: the body runs to EOF, which is exactly what we read.
+            body = rest
+        }
+        return HTTPResponse(status: status, headers: headers, body: body)
+    }
+
+    /// Index of the CRLFCRLF that ends the header block.
+    private static func findHeaderEnd(_ b: [UInt8]) -> Int? {
+        guard b.count >= 4 else { return nil }
+        for i in 0...(b.count - 4) where b[i] == 0x0D && b[i + 1] == 0x0A
+            && b[i + 2] == 0x0D && b[i + 3] == 0x0A {
+            return i
+        }
+        return nil
+    }
+
+    /// `Transfer-Encoding: chunked` decoding. hyper streams the art proxy this way, so this is a
+    /// live path, not defensive dead code.
+    static func decodeChunked(_ data: Data) throws -> Data {
+        let b = [UInt8](data)
+        var i = 0
+        var out = Data()
+        while true {
+            guard let lineEnd = findCRLF(b, from: i) else { throw HTTPParseError.malformedChunk }
+            // "1a" or "1a;ext=value" — the size is hex, any chunk extension is ignored.
+            let sizeField = String(decoding: b[i..<lineEnd], as: UTF8.self)
+                .split(separator: ";", maxSplits: 1, omittingEmptySubsequences: false)[0]
+                .trimmingCharacters(in: .whitespaces)
+            guard let size = Int(sizeField, radix: 16), size >= 0 else {
+                throw HTTPParseError.malformedChunk
+            }
+            i = lineEnd + 2
+            if size == 0 { return out } // terminal chunk; trailers (if any) are ignored
+            guard i + size <= b.count else { throw HTTPParseError.malformedChunk }
+            out.append(contentsOf: b[i..<(i + size)])
+            i += size
+            guard i + 1 < b.count, b[i] == 0x0D, b[i + 1] == 0x0A else {
+                throw HTTPParseError.malformedChunk
+            }
+            i += 2
+        }
+    }
+
+    private static func findCRLF(_ b: [UInt8], from: Int) -> Int? {
+        guard from >= 0, b.count >= 2 else { return nil }
+        var i = from
+        while i + 1 < b.count {
+            if b[i] == 0x0D && b[i + 1] == 0x0A { return i }
+            i += 1
+        }
+        return nil
+    }
+}
diff --git a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
index e8460fcf..dc90c624 100644
--- a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
+++ b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
@@ -83,6 +83,10 @@ public extension Array where Element == GameEntry {
 /// Errors surfaced to the UI so it can guide setup (the common case is "not paired yet").
 public enum LibraryError: LocalizedError {
     case unauthorized
+    /// The host's certificate didn't hash to the fingerprint pinned at pairing — an impostor, or
+    /// a host reinstalled/re-keyed since. Distinct from `unreachable` because the remedy is
+    /// completely different: re-pair, don't go hunting the network.
+    case pinMismatch
     case http(Int)
     case unreachable(String)
 
@@ -91,6 +95,9 @@ public enum LibraryError: LocalizedError {
         case .unauthorized:
             return "The host didn't recognize this device. Pair with the host first — it "
                 + "authorizes paired clients by their certificate (no token needed)."
+        case .pinMismatch:
+            return "The host's certificate doesn't match the one this device paired with. "
+                + "If the host was reinstalled, forget it here and pair again."
         case .http(let code):
             return "The management API returned HTTP \(code)."
         case .unreachable(let why):
@@ -122,47 +129,66 @@ public enum LibraryClient {
         keyPEM: String,
         hostFingerprint: Data?
     ) async throws -> [GameEntry] {
-        guard let url = URL(string: "https://\(address):\(port)/api/v1/library") else {
-            throw LibraryError.unreachable("invalid host address")
-        }
-        let identity: SecIdentity
-        do {
-            identity = try ClientTLS.makeIdentity(certPEM: certPEM, keyPEM: keyPEM)
-        } catch {
-            throw LibraryError.unreachable(
-                (error as? LocalizedError)?.errorDescription ?? error.localizedDescription)
-        }
-        let delegate = LibraryTLSDelegate(
-            identity: identity, pinnedHostFingerprint: hostFingerprint, host: address, port: port)
-        let session = URLSession(configuration: .ephemeral, delegate: delegate, delegateQueue: nil)
-        defer { session.finishTasksAndInvalidate() }
-
-        let req = URLRequest(url: url, timeoutInterval: 10)
-        let (data, response): (Data, URLResponse)
-        do {
-            (data, response) = try await session.data(for: req)
-        } catch {
-            throw LibraryError.unreachable(error.localizedDescription)
-        }
-        guard let http = response as? HTTPURLResponse else {
-            throw LibraryError.unreachable("not an HTTP response")
-        }
-        switch http.statusCode {
+        guard let base = URL(string: "\(baseURL(address: address, port: port))/api/v1/library")
+        else { throw LibraryError.unreachable("invalid host address") }
+        let identity = try clientIdentity(certPEM: certPEM, keyPEM: keyPEM)
+        let response = try await send(
+            path: "/api/v1/library", address: address, port: port,
+            identity: identity, hostFingerprint: hostFingerprint)
+        switch response.status {
         case 200:
-            var games = try JSONDecoder().decode([GameEntry].self, from: data)
-            // Steam art now comes back as host-relative proxy paths (`/api/v1/library/art/...`,
-            // see the host's `library::steam_art`) so they work the same regardless of which
+            var games = try JSONDecoder().decode([GameEntry].self, from: response.body)
+            // Steam art comes back as host-relative proxy paths (`/api/v1/library/art/...`, see
+            // the host's `library::steam_art`) so they work the same regardless of which
             // interface/port the client reached the host on. Resolve them against THIS host now,
             // so every other consumer just sees ordinary absolute URLs.
-            let base = url
             for i in games.indices {
                 games[i].art = games[i].art.resolved(against: base)
             }
             return games
-        case 401:
+        // 403 joins 401 here: both are the host declining this certificate, and the remedy the
+        // user needs is the same one.
+        case 401, 403:
             throw LibraryError.unauthorized
         default:
-            throw LibraryError.http(http.statusCode)
+            throw LibraryError.http(response.status)
+        }
+    }
+
+    /// `https://addr:port`, IPv6 literals bracketed — the mirror of the Rust client's `base_url`.
+    static func baseURL(address: String, port: UInt16) -> String {
+        let bare = address.hasPrefix("[") && address.hasSuffix("]")
+            ? String(address.dropFirst().dropLast()) : address
+        return bare.contains(":") ? "https://[\(bare)]:\(port)" : "https://\(bare):\(port)"
+    }
+
+    /// Build the paired identity, restating any keychain failure in the UI's vocabulary.
+    static func clientIdentity(certPEM: String, keyPEM: String) throws -> SecIdentity {
+        do {
+            return try ClientTLS.makeIdentity(certPEM: certPEM, keyPEM: keyPEM)
+        } catch {
+            throw LibraryError.unreachable(
+                (error as? LocalizedError)?.errorDescription ?? error.localizedDescription)
+        }
+    }
+
+    /// One GET against the host, with transport failures mapped onto `LibraryError`.
+    static func send(
+        path: String, address: String, port: UInt16,
+        identity: SecIdentity, hostFingerprint: Data?
+    ) async throws -> HTTPResponse {
+        do {
+            return try await MgmtTransport.get(
+                host: address, port: port, path: path,
+                identity: identity, pinnedHostFingerprint: hostFingerprint)
+        } catch MgmtTransportError.pinMismatch {
+            throw LibraryError.pinMismatch
+        } catch MgmtTransportError.timedOut {
+            throw LibraryError.unreachable("timed out")
+        } catch let error as MgmtTransportError {
+            throw LibraryError.unreachable(String(describing: error))
+        } catch {
+            throw LibraryError.unreachable(error.localizedDescription)
         }
     }
 }
@@ -186,23 +212,57 @@ extension Artwork {
     }
 }
 
-/// Builds the authenticated `URLSession` the library UI uses to fetch cover-art images — the same
-/// paired identity + host pinning as [`LibraryClient.fetch`], reused across a whole grid's worth of
-/// poster loads (this session is NOT one-shot: callers own its lifetime and should invalidate it
-/// when the view goes away). Safe to use for every candidate URL a `GameEntry`'s `Artwork` carries:
-/// `LibraryTLSDelegate` only pins/presents-cert for the host itself, deferring to normal system
-/// trust + no client cert for any other origin (an external CDN URL).
-public enum LibraryImageLoader {
-    public static func session(
+/// Loads cover art for the library UI, routing each URL to the transport that suits its origin.
+///
+/// A `GameEntry`'s art candidates mix two very different things: the host's own art proxy
+/// (`/api/v1/library/art/...`, resolved to absolute URLs against this host) and public store CDN
+/// URLs carried verbatim on custom/GOG/Heroic entries. Host URLs go over [`MgmtTransport`] with
+/// the paired identity and the pinned fingerprint — outside the URL loading system, so App
+/// Transport Security can stay ON app-wide. Every other origin keeps ordinary `URLSession` with
+/// full system trust evaluation and no client certificate, which is exactly what it should get.
+///
+/// Built once per library screen and reused across a whole grid's worth of posters.
+public final class LibraryArtLoader: @unchecked Sendable {
+    private let address: String
+    private let port: UInt16
+    private let identity: SecIdentity
+    private let hostFingerprint: Data?
+    /// Third-party origins only. No delegate: these are ordinary public HTTPS URLs and get the
+    /// system's normal certificate validation.
+    private let cdn = URLSession(configuration: .default)
+
+    public init(
         address: String,
         port: UInt16 = punktfunkDefaultMgmtPort,
         certPEM: String,
         keyPEM: String,
         hostFingerprint: Data?
-    ) throws -> URLSession {
-        let identity = try ClientTLS.makeIdentity(certPEM: certPEM, keyPEM: keyPEM)
-        let delegate = LibraryTLSDelegate(
-            identity: identity, pinnedHostFingerprint: hostFingerprint, host: address, port: port)
-        return URLSession(configuration: .default, delegate: delegate, delegateQueue: nil)
+    ) throws {
+        self.address = address
+        self.port = port
+        self.identity = try LibraryClient.clientIdentity(certPEM: certPEM, keyPEM: keyPEM)
+        self.hostFingerprint = hostFingerprint
+    }
+
+    public func data(for url: URL) async throws -> Data {
+        guard isHostOrigin(url) else { return try await cdn.data(from: url).0 }
+        var path = url.path.isEmpty ? "/" : url.path
+        if let query = url.query { path += "?\(query)" }
+        let response = try await LibraryClient.send(
+            path: path, address: address, port: port,
+            identity: identity, hostFingerprint: hostFingerprint)
+        guard response.status == 200 else { throw LibraryError.http(response.status) }
+        return response.body
+    }
+
+    /// Does this URL point at the host's own art proxy? Compared on host + port rather than a
+    /// string prefix, so a differently-spelled but equivalent URL still takes the pinned path.
+    private func isHostOrigin(_ url: URL) -> Bool {
+        guard let host = url.host else { return false }
+        let bare = address.hasPrefix("[") && address.hasSuffix("]")
+            ? String(address.dropFirst().dropLast()) : address
+        let scheme = url.scheme?.lowercased()
+        return host.caseInsensitiveCompare(bare) == .orderedSame
+            && (url.port ?? (scheme == "http" ? 80 : 443)) == Int(port)
     }
 }
diff --git a/clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift b/clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift
new file mode 100644
index 00000000..eb7fdada
--- /dev/null
+++ b/clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift
@@ -0,0 +1,184 @@
+// HTTPS transport for the host's management REST API, built on Network.framework rather than
+// URLSession.
+//
+// WHY NOT URLSession. App Transport Security governs the URL loading system, and its default
+// policy exempts only "local" destinations — `.local` names, unqualified names, and RFC1918 /
+// link-local IP literals. Everything else must present a certificate that passes system trust
+// evaluation. A punktfunk host is self-signed by construction (there is no CA that could vouch
+// for a box on someone's LAN), so the library worked at 192.168.x and died at the TLS layer on
+// every other address: a Tailscale peer (100.64/10 is CGNAT, NOT RFC1918), a WireGuard peer, or a
+// public IP. No ATS key can express "any address the user typed" — the exception keys are
+// domain-scoped — so the only ways out were disabling ATS app-wide (which also drops the TLS
+// floor and the cleartext block on third-party cover-art fetches, the one surface we did NOT want
+// to open) or leaving the URL loading system for this one origin. This is that second option.
+//
+// Network.framework is not subject to ATS, and `sec_protocol_options_set_verify_block` lets us
+// state the trust rule we actually mean: the leaf certificate must hash to the fingerprint the
+// user pinned during PIN pairing. That is a stronger check than CA trust here, not a weaker one,
+// and it is the same rule the QUIC stream plane has always applied via punktfunk-core — which is
+// precisely why streaming kept working over Tailscale while the library did not.
+
+import CryptoKit
+import Foundation
+import Network
+import Security
+
+enum MgmtTransportError: Error, Sendable {
+    /// The host's certificate did not hash to the pinned fingerprint — an impostor, or a host
+    /// that was reinstalled/re-keyed since pairing.
+    case pinMismatch
+    case connection(String)
+    case timedOut
+    case tooLarge
+}
+
+enum MgmtTransport {
+    /// Largest response we will buffer. The host's art proxy serves Steam hero images that run to
+    /// a few MB; anything past this is not a poster and not a library payload.
+    static let maxResponseBytes = 16 * 1024 * 1024
+
+    /// `GET https://host:port/path`, authenticated by mTLS (`identity`) and pinned by
+    /// `pinnedHostFingerprint` (nil = trust-on-first-use, matching the QUIC connect's semantics).
+    static func get(
+        host: String,
+        port: UInt16,
+        path: String,
+        identity: SecIdentity,
+        pinnedHostFingerprint: Data?,
+        timeout: TimeInterval = 15
+    ) async throws -> HTTPResponse {
+        guard let nwPort = NWEndpoint.Port(rawValue: port) else {
+            throw MgmtTransportError.connection("invalid port \(port)")
+        }
+        // One serial queue drives the connection, the verify block, and the timeout, so every
+        // touch of `Transfer` below is already serialized — no locking, and no chance of two
+        // callbacks racing to resume the continuation.
+        let queue = DispatchQueue(label: "io.unom.punktfunk.mgmt-transport")
+        let state = Transfer()
+        let options = tlsOptions(identity: identity, pin: pinnedHostFingerprint,
+                                 state: state, queue: queue)
+        let connection = NWConnection(
+            to: .hostPort(host: NWEndpoint.Host(unbracketed(host)), port: nwPort),
+            using: NWParameters(tls: options, tcp: NWProtocolTCP.Options()))
+        let request = requestBytes(host: host, port: port, path: path)
+
+        return try await withCheckedThrowingContinuation { continuation in
+            func finish(_ result: Result<HTTPResponse, Error>) {
+                guard !state.finished else { return }
+                state.finished = true
+                connection.cancel()
+                continuation.resume(with: result)
+            }
+
+            // A rejected pin surfaces as a generic handshake failure; `state.pinRejected` is how
+            // we recover what actually happened so the UI can say "re-pair" instead of "offline".
+            func fail(_ error: NWError) {
+                finish(.failure(state.pinRejected
+                    ? MgmtTransportError.pinMismatch
+                    : MgmtTransportError.connection(String(describing: error))))
+            }
+
+            func receiveLoop() {
+                connection.receive(minimumIncompleteLength: 1, maximumLength: 64 * 1024) {
+                    chunk, _, isComplete, error in
+                    if let chunk, !chunk.isEmpty { state.buffer.append(chunk) }
+                    if state.buffer.count > maxResponseBytes {
+                        finish(.failure(MgmtTransportError.tooLarge))
+                        return
+                    }
+                    if let error { fail(error); return }
+                    guard isComplete else { receiveLoop(); return }
+                    // `Connection: close` means EOF ends the response — parse what we have.
+                    finish(Result { try HTTPResponseParser.parse(state.buffer) })
+                }
+            }
+
+            connection.stateUpdateHandler = { newState in
+                switch newState {
+                case .ready:
+                    connection.send(content: request, completion: .contentProcessed { error in
+                        if let error { fail(error); return }
+                        receiveLoop()
+                    })
+                case .failed(let error):
+                    fail(error)
+                case .cancelled:
+                    // Only reachable via our own `finish`, which has already resumed; the guard
+                    // in `finish` makes this a no-op rather than a double-resume crash.
+                    finish(.failure(MgmtTransportError.connection("cancelled")))
+                default:
+                    break
+                }
+            }
+            queue.asyncAfter(deadline: .now() + timeout) {
+                finish(.failure(MgmtTransportError.timedOut))
+            }
+            connection.start(queue: queue)
+        }
+    }
+
+    /// Mutable per-request state. Confined to the transport's serial queue — see `get`.
+    private final class Transfer: @unchecked Sendable {
+        var finished = false
+        var pinRejected = false
+        var buffer = Data()
+    }
+
+    private static func tlsOptions(
+        identity: SecIdentity, pin: Data?, state: Transfer, queue: DispatchQueue
+    ) -> NWProtocolTLS.Options {
+        let options = NWProtocolTLS.Options()
+        let sec = options.securityProtocolOptions
+        sec_protocol_options_set_min_tls_protocol_version(sec, .TLSv12)
+        // Our half of the mTLS handshake: the same paired identity the host authorizes the
+        // read-only library routes by (mgmt/auth.rs `cert_may_access`).
+        if let secIdentity = sec_identity_create(identity) {
+            sec_protocol_options_set_local_identity(sec, secIdentity)
+        }
+        // Replaces system trust evaluation wholesale, which is the point: the host is self-signed
+        // and carries no SAN, so there is nothing for the system policy to succeed at. Pinning the
+        // leaf's SHA-256 is the real check.
+        sec_protocol_options_set_verify_block(sec, { _, trust, complete in
+            let secTrust = sec_trust_copy_ref(trust).takeRetainedValue()
+            guard let chain = SecTrustCopyCertificateChain(secTrust) as? [SecCertificate],
+                  let leaf = chain.first
+            else {
+                state.pinRejected = true
+                complete(false)
+                return
+            }
+            guard let pin else {
+                complete(true) // trust-on-first-use: no pin recorded for this host yet
+                return
+            }
+            let fingerprint = Data(SHA256.hash(data: SecCertificateCopyData(leaf) as Data))
+            let matches = fingerprint == pin
+            if !matches { state.pinRejected = true }
+            complete(matches)
+        }, queue)
+        return options
+    }
+
+    private static func requestBytes(host: String, port: UInt16, path: String) -> Data {
+        // An IPv6 literal is bracketed in the Host header (RFC 9110 §7.2); a name or IPv4 is not.
+        let bare = unbracketed(host)
+        let authority = bare.contains(":") ? "[\(bare)]:\(port)" : "\(bare):\(port)"
+        let request = """
+            GET \(path) HTTP/1.1\r
+            Host: \(authority)\r
+            User-Agent: punktfunk-apple\r
+            Accept: */*\r
+            Connection: close\r
+            \r
+
+            """
+        return Data(request.utf8)
+    }
+
+    /// Saved hosts store bare addresses, but a user who pasted a bracketed IPv6 literal shouldn't
+    /// get an unresolvable endpoint out of it.
+    private static func unbracketed(_ host: String) -> String {
+        guard host.hasPrefix("["), host.hasSuffix("]"), host.count > 2 else { return host }
+        return String(host.dropFirst().dropLast())
+    }
+}
diff --git a/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift b/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift
index 055a6d7b..84d789ab 100644
--- a/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift
+++ b/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift
@@ -78,4 +78,102 @@ final class LibraryClientTests: XCTestCase {
         XCTAssertEqual(resolved.hero, "https://cdn.example.com/hero.jpg") // unchanged
         XCTAssertNil(resolved.logo)
     }
+
+    // MARK: - HTTP response parsing (MgmtTransport)
+
+    // The management API is reached over Network.framework rather than URLSession (ATS cannot be
+    // relaxed for the arbitrary addresses a host lives at — see MgmtTransport), so we parse HTTP
+    // ourselves. These cover the framings hyper actually emits, plus the failure modes where
+    // getting it wrong would be silent.
+
+    private func raw(_ text: String) -> Data { Data(text.utf8) }
+
+    func testParsesContentLengthFramedJSON() throws {
+        let body = #"[{"id":"steam:570"}]"#
+        let response = try HTTPResponseParser.parse(raw(
+            "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n"
+                + "Content-Length: \(body.utf8.count)\r\n\r\n\(body)"))
+        XCTAssertEqual(response.status, 200)
+        XCTAssertEqual(String(decoding: response.body, as: UTF8.self), body)
+        // Field names are case-insensitive per RFC 9110.
+        XCTAssertEqual(response.header("CONTENT-TYPE"), "application/json")
+    }
+
+    func testParsesChunkedBody() throws {
+        // How hyper streams the art proxy.
+        let response = try HTTPResponseParser.parse(raw(
+            "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n"
+                + "5\r\nhello\r\n6\r\n world\r\n0\r\n\r\n"))
+        XCTAssertEqual(String(decoding: response.body, as: UTF8.self), "hello world")
+    }
+
+    func testChunkExtensionsAndTrailersAreIgnored() throws {
+        let response = try HTTPResponseParser.parse(raw(
+            "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n"
+                + "3;foo=bar\r\nabc\r\n0\r\nX-Trailer: 1\r\n\r\n"))
+        XCTAssertEqual(String(decoding: response.body, as: UTF8.self), "abc")
+    }
+
+    func testUnauthorizedStatusSurvives() throws {
+        // What an unpaired certificate gets from the host — the status is the whole signal.
+        let response = try HTTPResponseParser.parse(
+            raw("HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n"))
+        XCTAssertEqual(response.status, 401)
+        XCTAssertTrue(response.body.isEmpty)
+    }
+
+    func testBodyRunsToEOFWithoutFramingHeaders() throws {
+        let response = try HTTPResponseParser.parse(raw("HTTP/1.1 200 OK\r\n\r\nraw-to-eof"))
+        XCTAssertEqual(String(decoding: response.body, as: UTF8.self), "raw-to-eof")
+    }
+
+    func testTruncatedBodyThrowsRatherThanReturningPartialJSON() {
+        // The one that matters: a body cut short must NOT come back as success. A clipped JSON
+        // array would decode to fewer games — "this host has no games" — instead of an error.
+        XCTAssertThrowsError(
+            try HTTPResponseParser.parse(raw("HTTP/1.1 200 OK\r\nContent-Length: 99\r\n\r\nshort")))
+    }
+
+    func testOverLongBodyIsClippedToContentLength() throws {
+        let response = try HTTPResponseParser.parse(
+            raw("HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nabcdef"))
+        XCTAssertEqual(String(decoding: response.body, as: UTF8.self), "abc")
+    }
+
+    func testMalformedResponsesThrow() {
+        // Header block never terminated (peer hung up), a non-HTTP greeting, and a chunked stream
+        // cut mid-chunk.
+        XCTAssertThrowsError(
+            try HTTPResponseParser.parse(raw("HTTP/1.1 200 OK\r\nContent-Length: 3\r\n")))
+        XCTAssertThrowsError(try HTTPResponseParser.parse(raw("NOT-HTTP\r\n\r\n")))
+        XCTAssertThrowsError(try HTTPResponseParser.parse(raw(
+            "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n9\r\nabc")))
+    }
+
+    func testMultiWordReasonPhraseParses() throws {
+        let response = try HTTPResponseParser.parse(
+            raw("HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\n\r\n"))
+        XCTAssertEqual(response.status, 404)
+    }
+
+    func testBinaryBodySurvivesByteForByte() throws {
+        // Posters are PNG/JPEG: the body must never be round-tripped through a String.
+        let png: [UInt8] = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0xFF, 0x0D, 0x0A]
+        var message = raw("HTTP/1.1 200 OK\r\nContent-Length: \(png.count)\r\n\r\n")
+        message.append(contentsOf: png)
+        let response = try HTTPResponseParser.parse(message)
+        XCTAssertEqual([UInt8](response.body), png)
+    }
+
+    func testBaseURLBracketsIPv6Only() {
+        XCTAssertEqual(LibraryClient.baseURL(address: "192.168.1.70", port: 47990),
+                       "https://192.168.1.70:47990")
+        XCTAssertEqual(LibraryClient.baseURL(address: "100.101.102.103", port: 47990),
+                       "https://100.101.102.103:47990")
+        XCTAssertEqual(LibraryClient.baseURL(address: "fd7a:115c::1", port: 47990),
+                       "https://[fd7a:115c::1]:47990")
+        // An address the user pasted already bracketed must not end up double-bracketed.
+        XCTAssertEqual(LibraryClient.baseURL(address: "[fd7a:115c::1]", port: 47990),
+                       "https://[fd7a:115c::1]:47990")
+    }
 }

From 7798401f06be61245fde6403890c85c5e7404a6e Mon Sep 17 00:00:00 2001
From: enricobuehler <buehler@unom.io>
Date: Thu, 6 Aug 2026 10:09:55 +0200
Subject: [PATCH 4/4] perf(apple): cache posters on disk and pool the mgmt
 connections

Moving the management API onto Network.framework left one request per
connection, so a library grid paid a TLS handshake per poster where the pooled
URLSession had shared one. And the Apple client -- unlike Windows -- never
cached art at all, so it re-fetched every poster on every visit.

ArtCache: a size- and age-bounded blob cache in the CACHES directory (every byte
is re-derivable from the host, so the system is welcome to evict it). Keyed by
the SHA-256 of the absolute URL, so host-proxy paths and store CDN URLs share
one cache without colliding. Reads touch the entry, so eviction is by last USE,
not last write. Empty bodies and data: URLs are refused -- neither is worth a
file. Defaults: 128 MB, 30 days.

Connection pooling: MgmtConnectionPool keeps up to four keep-alive connections
per host and makes further callers wait rather than opening more, which is the
part that matters -- a grid can ask for dozens of posters at once. A connection
the host dropped since we last used it is indistinguishable from a live one
until we write, so a REUSED connection that fails is retried once on a fresh
one; a fresh failure is a real failure.

Keep-alive means a response can no longer be delimited by the peer hanging up,
so HTTPResponseParser.messageLength finds the end from the framing itself --
Content-Length or the chunked terminal chunk plus trailers. Getting that wrong
would truncate a response or bleed one into the next, silently, so it carries
the bulk of the new tests. A connection with bytes left over after a response is
dropped rather than reused: we never pipeline, so anything trailing means we are
out of sync.

LibraryView closes the loader's pooled connections on disappear instead of
leaving sockets open on a screen the user has left.

16 new tests: message framing (both encodings, partial reads, back-to-back
responses, close detection) and the cache (binary round trip, key separation,
refusals, expiry, LRU eviction).
---
 .../PunktfunkKit/Connection/ArtCache.swift    | 116 ++++++
 .../Connection/HTTPResponse.swift             | 134 +++++--
 .../Connection/LibraryClient.swift            |  20 +
 .../Connection/MgmtTransport.swift            | 353 ++++++++++++++----
 .../LibraryClientTests.swift                  | 132 +++++++
 5 files changed, 641 insertions(+), 114 deletions(-)
 create mode 100644 clients/apple/Sources/PunktfunkKit/Connection/ArtCache.swift

diff --git a/clients/apple/Sources/PunktfunkKit/Connection/ArtCache.swift b/clients/apple/Sources/PunktfunkKit/Connection/ArtCache.swift
new file mode 100644
index 00000000..5953be03
--- /dev/null
+++ b/clients/apple/Sources/PunktfunkKit/Connection/ArtCache.swift
@@ -0,0 +1,116 @@
+// On-disk cache for library cover art.
+//
+// Posters are the bulk of what the library screen transfers and they essentially never change, so
+// re-fetching them on every visit is pure waste — the Windows client has cached them on disk for
+// this reason and Apple did not. It matters more now that host art rides `MgmtTransport`: a cache
+// hit costs no connection at all.
+//
+// Lives in the CACHES directory on purpose: every byte here is re-derivable from the host, so the
+// system is welcome to evict it under storage pressure. Entries are keyed by the SHA-256 of the
+// absolute URL, which covers both host-proxy paths and store CDN URLs without either colliding.
+//
+// Deliberately free of any Network.framework / PunktfunkCore dependency, so it can be unit-tested
+// against a temporary directory.
+
+import CryptoKit
+import Foundation
+
+/// A size- and age-bounded blob cache. An actor so disk work stays off whichever thread the
+/// SwiftUI poster view happens to be on, and so pruning can never race a write.
+actor ArtCache {
+    private let directory: URL
+    private let maxBytes: Int
+    private let maxAge: TimeInterval
+    private let fileManager = FileManager.default
+
+    /// `directory` is created on demand. Defaults: 128 MB — a 200-title library of 600×900
+    /// capsules lands far under that — and 30 days, which only matters for art a host later
+    /// replaces.
+    init(directory: URL, maxBytes: Int = 128 * 1024 * 1024, maxAge: TimeInterval = 30 * 24 * 3600) {
+        self.directory = directory
+        self.maxBytes = maxBytes
+        self.maxAge = maxAge
+    }
+
+    /// The app's standard location, or nil if the caches directory is unavailable (in which case
+    /// callers simply run without a cache rather than failing).
+    static func standard() -> ArtCache? {
+        guard let caches = FileManager.default.urls(
+            for: .cachesDirectory, in: .userDomainMask).first
+        else { return nil }
+        return ArtCache(directory: caches.appendingPathComponent("PunktfunkArt", isDirectory: true))
+    }
+
+    func data(for url: URL) -> Data? {
+        let file = path(for: url)
+        guard let data = try? Data(contentsOf: file) else { return nil }
+        // Age out stale art rather than serving it forever.
+        if let modified = modificationDate(of: file), Date().timeIntervalSince(modified) > maxAge {
+            try? fileManager.removeItem(at: file)
+            return nil
+        }
+        // Touch, so eviction can order by last USE rather than last write.
+        try? fileManager.setAttributes([.modificationDate: Date()], ofItemAtPath: file.path)
+        return data
+    }
+
+    func store(_ data: Data, for url: URL) {
+        // An empty body is not art, and a `data:` URL is already inline — caching either is a
+        // pure loss.
+        guard !data.isEmpty, url.scheme?.lowercased() != "data" else { return }
+        do {
+            try fileManager.createDirectory(at: directory, withIntermediateDirectories: true)
+            try data.write(to: path(for: url), options: .atomic)
+        } catch {
+            return // a cache that can't write is a slow cache, not a broken app
+        }
+        prune()
+    }
+
+    /// Drop the oldest entries until the directory fits the budget. Also removes anything past
+    /// `maxAge` so a cache that is under budget still doesn't hoard stale art forever.
+    func prune() {
+        let keys: [URLResourceKey] = [.contentModificationDateKey, .fileSizeKey]
+        guard let entries = try? fileManager.contentsOfDirectory(
+            at: directory, includingPropertiesForKeys: keys, options: .skipsHiddenFiles)
+        else { return }
+
+        var files: [(url: URL, date: Date, size: Int)] = []
+        var total = 0
+        let now = Date()
+        for entry in entries {
+            let values = try? entry.resourceValues(forKeys: Set(keys))
+            let date = values?.contentModificationDate ?? .distantPast
+            let size = values?.fileSize ?? 0
+            if now.timeIntervalSince(date) > maxAge {
+                try? fileManager.removeItem(at: entry)
+                continue
+            }
+            files.append((entry, date, size))
+            total += size
+        }
+        guard total > maxBytes else { return }
+
+        // Oldest first — `data(for:)` touches on read, so this is least-recently-USED.
+        for file in files.sorted(by: { $0.date < $1.date }) {
+            guard total > maxBytes else { break }
+            try? fileManager.removeItem(at: file.url)
+            total -= file.size
+        }
+    }
+
+    /// Wipe the cache — for a "clear cached data" affordance, and for tests.
+    func clear() {
+        try? fileManager.removeItem(at: directory)
+    }
+
+    private func path(for url: URL) -> URL {
+        let digest = SHA256.hash(data: Data(url.absoluteString.utf8))
+        let name = digest.map { String(format: "%02x", $0) }.joined()
+        return directory.appendingPathComponent(name, isDirectory: false)
+    }
+
+    private func modificationDate(of file: URL) -> Date? {
+        (try? file.resourceValues(forKeys: [.contentModificationDateKey]))?.contentModificationDate
+    }
+}
diff --git a/clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift b/clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift
index 1c604cd7..ae61ea8f 100644
--- a/clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift
+++ b/clients/apple/Sources/PunktfunkKit/Connection/HTTPResponse.swift
@@ -3,10 +3,14 @@
 // We speak HTTP ourselves because the management API has to be reached OUTSIDE the URL loading
 // system: App Transport Security applies to URLSession and cannot be relaxed for the arbitrary,
 // user-supplied addresses a punktfunk host lives at (see MgmtTransport for the full story). What
-// we need is one unauthenticated-by-header GET per request, so this covers exactly that and
-// nothing more — no redirects, no keep-alive, no request bodies, no content negotiation.
+// we need is GETs against one host, so this covers exactly that and nothing more — no redirects,
+// no request bodies, no content negotiation.
 //
-// Deliberately free of any Network.framework / PunktfunkCore dependency: it is pure bytes-in,
+// It does need to find where a response ENDS without waiting for the peer to hang up, because the
+// connection is reused across a grid's worth of poster fetches (`messageLength`). Both framings
+// hyper emits are handled: `Content-Length`, and `Transfer-Encoding: chunked` for the art proxy.
+//
+// Deliberately free of any Network.framework / PunktfunkCore dependency: pure bytes-in,
 // value-out, so it can be unit-tested (and typechecked) on its own.
 
 import Foundation
@@ -19,6 +23,11 @@ struct HTTPResponse: Sendable {
     let body: Data
 
     func header(_ name: String) -> String? { headers[name.lowercased()] }
+
+    /// Did the peer ask to close? HTTP/1.1 keeps the connection open unless it says otherwise.
+    var wantsClose: Bool {
+        header("connection")?.lowercased().contains("close") ?? false
+    }
 }
 
 enum HTTPParseError: Error, Sendable {
@@ -32,14 +41,60 @@ enum HTTPParseError: Error, Sendable {
 }
 
 enum HTTPResponseParser {
-    /// Parse a complete response — everything read from the socket until EOF.
+    /// Byte length of the first complete response in `raw`, or nil when more bytes are needed.
+    ///
+    /// Also nil when the response carries no framing header at all, since then the body runs
+    /// until the peer closes and has no knowable length — a connection that answers that way
+    /// cannot be reused.
+    static func messageLength(in raw: Data) throws -> Int? {
+        let b = [UInt8](raw)
+        guard let head = try parseHead(b) else { return nil }
+        if head.headers["transfer-encoding"]?.lowercased().contains("chunked") == true {
+            return try chunkedEnd(b, from: head.bodyStart)
+        }
+        if let field = head.headers["content-length"] {
+            guard let length = Int(field.trimmingCharacters(in: .whitespaces)), length >= 0 else {
+                throw HTTPParseError.malformedHeader
+            }
+            let end = head.bodyStart + length
+            return b.count >= end ? end : nil
+        }
+        return nil // framed by connection close
+    }
+
+    /// Parse one complete response. `raw` must hold exactly one message (use `messageLength` to
+    /// slice it) or, for a close-framed response, everything read up to EOF.
     static func parse(_ raw: Data) throws -> HTTPResponse {
-        let bytes = [UInt8](raw)
-        guard let headEnd = findHeaderEnd(bytes) else { throw HTTPParseError.truncated }
-        // Header field-values are ISO-8859-1 by the grammar; decoding that way never fails, which
-        // keeps a stray non-UTF-8 byte in some header from failing the whole response.
-        let head = String(decoding: bytes[0..<headEnd], as: UTF8.self)
-        var lines = head.components(separatedBy: "\r\n")
+        let b = [UInt8](raw)
+        guard let head = try parseHead(b) else { throw HTTPParseError.truncated }
+        let rest = Data(b[head.bodyStart...])
+        let body: Data
+        if head.headers["transfer-encoding"]?.lowercased().contains("chunked") == true {
+            body = try decodeChunked(rest)
+        } else if let field = head.headers["content-length"] {
+            guard let length = Int(field.trimmingCharacters(in: .whitespaces)), length >= 0 else {
+                throw HTTPParseError.malformedHeader
+            }
+            guard rest.count >= length else { throw HTTPParseError.truncated }
+            body = rest.prefix(length)
+        } else {
+            body = rest // framed by connection close: what we read is what there is
+        }
+        return HTTPResponse(status: head.status, headers: head.headers, body: body)
+    }
+
+    private struct Head {
+        let status: Int
+        let headers: [String: String]
+        /// Offset of the first body byte (just past the CRLFCRLF).
+        let bodyStart: Int
+    }
+
+    /// Status line + header block, or nil if the block hasn't fully arrived.
+    private static func parseHead(_ b: [UInt8]) throws -> Head? {
+        guard let headEnd = findHeaderEnd(b) else { return nil }
+        let text = String(decoding: b[0..<headEnd], as: UTF8.self)
+        var lines = text.components(separatedBy: "\r\n")
         guard !lines.isEmpty else { throw HTTPParseError.malformedStatusLine }
 
         // "HTTP/1.1 200 OK" — the reason phrase is optional and ignored.
@@ -63,24 +118,10 @@ enum HTTPResponseParser {
             // silently would be a lie.
             headers[name] = headers[name].map { "\($0), \(value)" } ?? value
         }
-
-        let rest = Data(bytes[(headEnd + 4)...])
-        let body: Data
-        if headers["transfer-encoding"]?.lowercased().contains("chunked") == true {
-            body = try decodeChunked(rest)
-        } else if let lengthField = headers["content-length"] {
-            guard let length = Int(lengthField.trimmingCharacters(in: .whitespaces)), length >= 0
-            else { throw HTTPParseError.malformedHeader }
-            guard rest.count >= length else { throw HTTPParseError.truncated }
-            body = rest.prefix(length)
-        } else {
-            // No framing header: the body runs to EOF, which is exactly what we read.
-            body = rest
-        }
-        return HTTPResponse(status: status, headers: headers, body: body)
+        return Head(status: status, headers: headers, bodyStart: headEnd + 4)
     }
 
-    /// Index of the CRLFCRLF that ends the header block.
+    /// Index just past the CRLFCRLF that ends the header block.
     private static func findHeaderEnd(_ b: [UInt8]) -> Int? {
         guard b.count >= 4 else { return nil }
         for i in 0...(b.count - 4) where b[i] == 0x0D && b[i + 1] == 0x0A
@@ -90,6 +131,28 @@ enum HTTPResponseParser {
         return nil
     }
 
+    /// Offset just past a complete chunked body (terminal chunk plus any trailers), or nil if it
+    /// hasn't all arrived.
+    private static func chunkedEnd(_ b: [UInt8], from start: Int) throws -> Int? {
+        var i = start
+        while true {
+            guard let lineEnd = findCRLF(b, from: i) else { return nil }
+            guard let size = chunkSize(b, i, lineEnd) else { throw HTTPParseError.malformedChunk }
+            i = lineEnd + 2
+            if size == 0 {
+                // Terminal chunk. Trailers (if any) run to the next empty line.
+                var j = i
+                while true {
+                    guard let end = findCRLF(b, from: j) else { return nil }
+                    if end == j { return j + 2 }
+                    j = end + 2
+                }
+            }
+            guard i + size + 2 <= b.count else { return nil }
+            i += size + 2 // payload plus its trailing CRLF
+        }
+    }
+
     /// `Transfer-Encoding: chunked` decoding. hyper streams the art proxy this way, so this is a
     /// live path, not defensive dead code.
     static func decodeChunked(_ data: Data) throws -> Data {
@@ -98,15 +161,9 @@ enum HTTPResponseParser {
         var out = Data()
         while true {
             guard let lineEnd = findCRLF(b, from: i) else { throw HTTPParseError.malformedChunk }
-            // "1a" or "1a;ext=value" — the size is hex, any chunk extension is ignored.
-            let sizeField = String(decoding: b[i..<lineEnd], as: UTF8.self)
-                .split(separator: ";", maxSplits: 1, omittingEmptySubsequences: false)[0]
-                .trimmingCharacters(in: .whitespaces)
-            guard let size = Int(sizeField, radix: 16), size >= 0 else {
-                throw HTTPParseError.malformedChunk
-            }
+            guard let size = chunkSize(b, i, lineEnd) else { throw HTTPParseError.malformedChunk }
             i = lineEnd + 2
-            if size == 0 { return out } // terminal chunk; trailers (if any) are ignored
+            if size == 0 { return out } // terminal chunk; trailers are ignored
             guard i + size <= b.count else { throw HTTPParseError.malformedChunk }
             out.append(contentsOf: b[i..<(i + size)])
             i += size
@@ -117,6 +174,15 @@ enum HTTPResponseParser {
         }
     }
 
+    /// "1a" or "1a;ext=value" → 26. Nil if it isn't a hex size.
+    private static func chunkSize(_ b: [UInt8], _ from: Int, _ to: Int) -> Int? {
+        let field = String(decoding: b[from..<to], as: UTF8.self)
+            .split(separator: ";", maxSplits: 1, omittingEmptySubsequences: false)[0]
+            .trimmingCharacters(in: .whitespaces)
+        guard let size = Int(field, radix: 16), size >= 0 else { return nil }
+        return size
+    }
+
     private static func findCRLF(_ b: [UInt8], from: Int) -> Int? {
         guard from >= 0, b.count >= 2 else { return nil }
         var i = from
diff --git a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
index dc90c624..91e0035c 100644
--- a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
+++ b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift
@@ -221,6 +221,10 @@ extension Artwork {
 /// Transport Security can stay ON app-wide. Every other origin keeps ordinary `URLSession` with
 /// full system trust evaluation and no client certificate, which is exactly what it should get.
 ///
+/// Posters are cached on disk (`ArtCache`), so a second visit to a library costs no network at
+/// all — and the connections behind a first visit are pooled and kept alive rather than paying a
+/// TLS handshake per tile.
+///
 /// Built once per library screen and reused across a whole grid's worth of posters.
 public final class LibraryArtLoader: @unchecked Sendable {
     private let address: String
@@ -230,6 +234,8 @@ public final class LibraryArtLoader: @unchecked Sendable {
     /// Third-party origins only. No delegate: these are ordinary public HTTPS URLs and get the
     /// system's normal certificate validation.
     private let cdn = URLSession(configuration: .default)
+    /// nil when the caches directory is unavailable — then we simply always fetch.
+    private let cache = ArtCache.standard()
 
     public init(
         address: String,
@@ -245,6 +251,20 @@ public final class LibraryArtLoader: @unchecked Sendable {
     }
 
     public func data(for url: URL) async throws -> Data {
+        if let cache, let cached = await cache.data(for: url) { return cached }
+        let fetched = try await fetch(url)
+        if let cache { await cache.store(fetched, for: url) }
+        return fetched
+    }
+
+    /// Release this host's pooled connections — call when the library screen goes away, so we
+    /// don't sit on open TLS sockets the user is finished with.
+    public func close() async {
+        await MgmtConnectionPool.shared.closeAll(
+            matching: "\(MgmtTransport.unbracketed(address)):\(port):")
+    }
+
+    private func fetch(_ url: URL) async throws -> Data {
         guard isHostOrigin(url) else { return try await cdn.data(from: url).0 }
         var path = url.path.isEmpty ? "/" : url.path
         if let query = url.query { path += "?\(query)" }
diff --git a/clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift b/clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift
index eb7fdada..af931cc3 100644
--- a/clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift
+++ b/clients/apple/Sources/PunktfunkKit/Connection/MgmtTransport.swift
@@ -17,6 +17,11 @@
 // user pinned during PIN pairing. That is a stronger check than CA trust here, not a weaker one,
 // and it is the same rule the QUIC stream plane has always applied via punktfunk-core — which is
 // precisely why streaming kept working over Tailscale while the library did not.
+//
+// Connections are POOLED and kept alive: a library screen fetches one JSON payload and then a
+// poster per title, and giving each its own TLS handshake was pure latency. `MgmtConnectionPool`
+// keeps a small number of connections per host, hands them out one request at a time, and makes
+// callers wait rather than opening an unbounded number.
 
 import CryptoKit
 import Foundation
@@ -30,6 +35,7 @@ enum MgmtTransportError: Error, Sendable {
     case connection(String)
     case timedOut
     case tooLarge
+    case invalidPort(UInt16)
 }
 
 enum MgmtTransport {
@@ -39,6 +45,10 @@ enum MgmtTransport {
 
     /// `GET https://host:port/path`, authenticated by mTLS (`identity`) and pinned by
     /// `pinnedHostFingerprint` (nil = trust-on-first-use, matching the QUIC connect's semantics).
+    ///
+    /// Runs over a pooled keep-alive connection. A connection the host has since dropped is
+    /// indistinguishable from a live one until we write to it, so a REUSED connection that fails
+    /// is retried once on a fresh one; a fresh connection that fails is a real error.
     static func get(
         host: String,
         port: UInt16,
@@ -48,85 +58,134 @@ enum MgmtTransport {
         timeout: TimeInterval = 15
     ) async throws -> HTTPResponse {
         guard let nwPort = NWEndpoint.Port(rawValue: port) else {
-            throw MgmtTransportError.connection("invalid port \(port)")
+            throw MgmtTransportError.invalidPort(port)
         }
-        // One serial queue drives the connection, the verify block, and the timeout, so every
-        // touch of `Transfer` below is already serialized — no locking, and no chance of two
-        // callbacks racing to resume the continuation.
-        let queue = DispatchQueue(label: "io.unom.punktfunk.mgmt-transport")
-        let state = Transfer()
-        let options = tlsOptions(identity: identity, pin: pinnedHostFingerprint,
-                                 state: state, queue: queue)
-        let connection = NWConnection(
-            to: .hostPort(host: NWEndpoint.Host(unbracketed(host)), port: nwPort),
-            using: NWParameters(tls: options, tcp: NWProtocolTCP.Options()))
-        let request = requestBytes(host: host, port: port, path: path)
+        let pin = pinnedHostFingerprint
+        let key = "\(unbracketed(host)):\(port):\(pin.map(hex) ?? "tofu")"
+        var lastError: Error = MgmtTransportError.connection("no attempt made")
 
-        return try await withCheckedThrowingContinuation { continuation in
-            func finish(_ result: Result<HTTPResponse, Error>) {
-                guard !state.finished else { return }
-                state.finished = true
-                connection.cancel()
-                continuation.resume(with: result)
+        for attempt in 0..<2 {
+            let connection = await MgmtConnectionPool.shared.acquire(key: key) {
+                MgmtConnection(host: unbracketed(host), port: nwPort, identity: identity, pin: pin)
             }
+            let wasReused = connection.hasServedRequest
+            do {
+                let response = try await connection.perform(path: path, timeout: timeout)
+                await MgmtConnectionPool.shared.release(connection, key: key)
+                return response
+            } catch {
+                await MgmtConnectionPool.shared.release(connection, key: key)
+                lastError = error
+                // Only a reused connection earns a second try, and only once: retrying a fresh
+                // connection would just double every genuine failure's latency.
+                if !wasReused || attempt == 1 { throw error }
+            }
+        }
+        throw lastError
+    }
 
-            // A rejected pin surfaces as a generic handshake failure; `state.pinRejected` is how
-            // we recover what actually happened so the UI can say "re-pair" instead of "offline".
-            func fail(_ error: NWError) {
-                finish(.failure(state.pinRejected
-                    ? MgmtTransportError.pinMismatch
-                    : MgmtTransportError.connection(String(describing: error))))
-            }
+    static func hex(_ data: Data) -> String {
+        data.map { String(format: "%02x", $0) }.joined()
+    }
 
-            func receiveLoop() {
-                connection.receive(minimumIncompleteLength: 1, maximumLength: 64 * 1024) {
-                    chunk, _, isComplete, error in
-                    if let chunk, !chunk.isEmpty { state.buffer.append(chunk) }
-                    if state.buffer.count > maxResponseBytes {
-                        finish(.failure(MgmtTransportError.tooLarge))
-                        return
-                    }
-                    if let error { fail(error); return }
-                    guard isComplete else { receiveLoop(); return }
-                    // `Connection: close` means EOF ends the response — parse what we have.
-                    finish(Result { try HTTPResponseParser.parse(state.buffer) })
-                }
-            }
+    /// Saved hosts store bare addresses, but a user who pasted a bracketed IPv6 literal shouldn't
+    /// get an unresolvable endpoint out of it.
+    static func unbracketed(_ host: String) -> String {
+        guard host.hasPrefix("["), host.hasSuffix("]"), host.count > 2 else { return host }
+        return String(host.dropFirst().dropLast())
+    }
+}
 
-            connection.stateUpdateHandler = { newState in
-                switch newState {
-                case .ready:
-                    connection.send(content: request, completion: .contentProcessed { error in
-                        if let error { fail(error); return }
-                        receiveLoop()
-                    })
-                case .failed(let error):
-                    fail(error)
-                case .cancelled:
-                    // Only reachable via our own `finish`, which has already resumed; the guard
-                    // in `finish` makes this a no-op rather than a double-resume crash.
-                    finish(.failure(MgmtTransportError.connection("cancelled")))
-                default:
-                    break
-                }
+/// A pool of keep-alive connections, at most `maxPerHost` per host. Callers past that wait for one
+/// to come back rather than opening more — a library grid can ask for dozens of posters at once,
+/// and answering that with dozens of TLS handshakes is what this exists to prevent.
+actor MgmtConnectionPool {
+    static let shared = MgmtConnectionPool()
+
+    private var available: [String: [MgmtConnection]] = [:]
+    /// Connections created and not yet closed, per host — the cap this pool enforces.
+    private var live: [String: Int] = [:]
+    private var waiters: [String: [CheckedContinuation<Void, Never>]] = [:]
+    private let maxPerHost = 4
+
+    func acquire(key: String, make: () -> MgmtConnection) async -> MgmtConnection {
+        while true {
+            if var idle = available[key], let connection = idle.popLast() {
+                available[key] = idle
+                if connection.isHealthy { return connection }
+                connection.close()
+                live[key] = max(0, (live[key] ?? 1) - 1)
+                continue
             }
-            queue.asyncAfter(deadline: .now() + timeout) {
-                finish(.failure(MgmtTransportError.timedOut))
+            if (live[key] ?? 0) < maxPerHost {
+                live[key] = (live[key] ?? 0) + 1
+                return make()
+            }
+            await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+                waiters[key, default: []].append(continuation)
             }
-            connection.start(queue: queue)
         }
     }
 
-    /// Mutable per-request state. Confined to the transport's serial queue — see `get`.
-    private final class Transfer: @unchecked Sendable {
-        var finished = false
-        var pinRejected = false
-        var buffer = Data()
+    /// Always call this, on success AND on failure: a connection that is never returned leaks a
+    /// slot, and enough leaked slots would hang every later request on the waiter queue.
+    func release(_ connection: MgmtConnection, key: String) {
+        if connection.isHealthy, (available[key]?.count ?? 0) < maxPerHost {
+            available[key, default: []].append(connection)
+        } else {
+            connection.close()
+            live[key] = max(0, (live[key] ?? 1) - 1)
+        }
+        if var queue = waiters[key], !queue.isEmpty {
+            let next = queue.removeFirst()
+            waiters[key] = queue
+            next.resume()
+        }
     }
 
-    private static func tlsOptions(
-        identity: SecIdentity, pin: Data?, state: Transfer, queue: DispatchQueue
-    ) -> NWProtocolTLS.Options {
+    /// Drop every idle connection for a host — used when a library screen goes away, so we don't
+    /// sit on sockets the user is done with.
+    func closeAll(matching prefix: String) {
+        for (key, connections) in available where key.hasPrefix(prefix) {
+            connections.forEach { $0.close() }
+            live[key] = max(0, (live[key] ?? 0) - connections.count)
+            available[key] = []
+        }
+    }
+}
+
+/// One TLS connection to a host, serving requests one at a time. The pool guarantees a single
+/// caller at a time, so there is no request queueing here.
+///
+/// Everything mutable is touched only on `queue`, which also runs the connection's callbacks, the
+/// verify block and the timeout — so the state below needs no locking and two callbacks can never
+/// race to resume the same continuation.
+final class MgmtConnection: @unchecked Sendable {
+    private let queue = DispatchQueue(label: "io.unom.punktfunk.mgmt-connection")
+    private let connection: NWConnection
+    private let host: String
+    private let port: UInt16
+
+    private enum Phase { case idle, connecting, ready, dead }
+    private var phase: Phase = .idle
+    private var pending: CheckedContinuation<HTTPResponse, Error>?
+    private var pendingRequest: Data?
+    /// Bytes read past the end of the last response. Non-empty only if a host pipelines ahead of
+    /// us, which none do — but dropping them would silently corrupt the next read.
+    private var buffer = Data()
+    private var operation = 0
+    private var pinRejected = false
+    private var servedRequest = false
+
+    /// False once the connection has failed; the pool discards these instead of handing them out.
+    private(set) var isHealthy = true
+    /// Has this connection completed at least one request? Drives the retry-once rule in
+    /// `MgmtTransport.get` — only a connection the host may have dropped since is worth retrying.
+    var hasServedRequest: Bool { servedRequest }
+
+    init(host: String, port: NWEndpoint.Port, identity: SecIdentity, pin: Data?) {
+        self.host = host
+        self.port = port.rawValue
         let options = NWProtocolTLS.Options()
         let sec = options.securityProtocolOptions
         sec_protocol_options_set_min_tls_protocol_version(sec, .TLSv12)
@@ -135,6 +194,7 @@ enum MgmtTransport {
         if let secIdentity = sec_identity_create(identity) {
             sec_protocol_options_set_local_identity(sec, secIdentity)
         }
+        let rejected = RejectionFlag()
         // Replaces system trust evaluation wholesale, which is the point: the host is self-signed
         // and carries no SAN, so there is nothing for the system policy to succeed at. Pinning the
         // leaf's SHA-256 is the real check.
@@ -143,7 +203,7 @@ enum MgmtTransport {
             guard let chain = SecTrustCopyCertificateChain(secTrust) as? [SecCertificate],
                   let leaf = chain.first
             else {
-                state.pinRejected = true
+                rejected.value = true
                 complete(false)
                 return
             }
@@ -153,32 +213,165 @@ enum MgmtTransport {
             }
             let fingerprint = Data(SHA256.hash(data: SecCertificateCopyData(leaf) as Data))
             let matches = fingerprint == pin
-            if !matches { state.pinRejected = true }
+            if !matches { rejected.value = true }
             complete(matches)
         }, queue)
-        return options
+        self.connection = NWConnection(
+            to: .hostPort(host: NWEndpoint.Host(host), port: port),
+            using: NWParameters(tls: options, tcp: NWProtocolTCP.Options()))
+        self.rejection = rejected
+        self.connection.stateUpdateHandler = { [weak self] state in
+            self?.handle(state)
+        }
     }
 
-    private static func requestBytes(host: String, port: UInt16, path: String) -> Data {
+    /// Set from the verify block, read when mapping the resulting handshake failure. Its own
+    /// object because the block is built before `self` exists.
+    private let rejection: RejectionFlag
+    private final class RejectionFlag: @unchecked Sendable { var value = false }
+
+    func perform(path: String, timeout: TimeInterval) async throws -> HTTPResponse {
+        try await withCheckedThrowingContinuation { continuation in
+            queue.async {
+                guard self.phase != .dead else {
+                    continuation.resume(throwing: MgmtTransportError.connection("connection closed"))
+                    return
+                }
+                self.operation += 1
+                let op = self.operation
+                self.pending = continuation
+                self.pendingRequest = self.requestBytes(path: path)
+                self.buffer.removeAll(keepingCapacity: true)
+                self.queue.asyncAfter(deadline: .now() + timeout) { [weak self] in
+                    guard let self, self.operation == op else { return }
+                    self.finish(.failure(MgmtTransportError.timedOut))
+                }
+                switch self.phase {
+                case .idle:
+                    self.phase = .connecting
+                    self.connection.start(queue: self.queue)
+                case .ready:
+                    self.send()
+                case .connecting, .dead:
+                    break // `.ready` (or a failure) will pick the pending request up
+                }
+            }
+        }
+    }
+
+    func close() {
+        queue.async {
+            self.phase = .dead
+            self.isHealthy = false
+            self.connection.cancel()
+        }
+    }
+
+    // MARK: - Queue-confined internals
+
+    private func handle(_ state: NWConnection.State) {
+        switch state {
+        case .ready:
+            phase = .ready
+            if pendingRequest != nil { send() }
+        case .failed(let error):
+            phase = .dead
+            isHealthy = false
+            finish(.failure(mapped(error)))
+        case .cancelled:
+            phase = .dead
+            isHealthy = false
+            finish(.failure(MgmtTransportError.connection("cancelled")))
+        default:
+            break
+        }
+    }
+
+    private func send() {
+        guard let request = pendingRequest else { return }
+        pendingRequest = nil
+        connection.send(content: request, completion: .contentProcessed { [weak self] error in
+            guard let self else { return }
+            if let error {
+                self.isHealthy = false
+                self.finish(.failure(self.mapped(error)))
+                return
+            }
+            self.receive()
+        })
+    }
+
+    private func receive() {
+        connection.receive(minimumIncompleteLength: 1, maximumLength: 64 * 1024) {
+            [weak self] chunk, _, isComplete, error in
+            guard let self else { return }
+            if let chunk, !chunk.isEmpty { self.buffer.append(chunk) }
+            if self.buffer.count > MgmtTransport.maxResponseBytes {
+                self.isHealthy = false
+                self.finish(.failure(MgmtTransportError.tooLarge))
+                return
+            }
+            if let error {
+                self.isHealthy = false
+                self.finish(.failure(self.mapped(error)))
+                return
+            }
+            do {
+                if let length = try HTTPResponseParser.messageLength(in: self.buffer) {
+                    let message = self.buffer.prefix(length)
+                    self.buffer = Data(self.buffer.dropFirst(length))
+                    let response = try HTTPResponseParser.parse(message)
+                    // A response the peer means to be last leaves nothing reusable behind. Nor
+                    // does a stream with bytes left over: we never pipeline, so anything trailing
+                    // means we are out of sync, and reusing the connection would misread the next
+                    // response rather than fail cleanly.
+                    if response.wantsClose || !self.buffer.isEmpty { self.isHealthy = false }
+                    self.servedRequest = true
+                    self.finish(.success(response))
+                    return
+                }
+                if isComplete {
+                    // No framing header: the body ran to EOF, so what we have is the whole thing
+                    // and the connection is spent.
+                    self.isHealthy = false
+                    let response = try HTTPResponseParser.parse(self.buffer)
+                    self.servedRequest = true
+                    self.finish(.success(response))
+                    return
+                }
+            } catch {
+                self.isHealthy = false
+                self.finish(.failure(error))
+                return
+            }
+            self.receive()
+        }
+    }
+
+    private func finish(_ result: Result<HTTPResponse, Error>) {
+        guard let continuation = pending else { return }
+        pending = nil
+        operation += 1 // invalidate this operation's timeout
+        continuation.resume(with: result)
+    }
+
+    /// A rejected pin surfaces as a generic handshake failure; the flag is how we recover what
+    /// actually happened, so the UI can say "re-pair" instead of "offline".
+    private func mapped(_ error: NWError) -> MgmtTransportError {
+        rejection.value ? .pinMismatch : .connection(String(describing: error))
+    }
+
+    private func requestBytes(path: String) -> Data {
         // An IPv6 literal is bracketed in the Host header (RFC 9110 §7.2); a name or IPv4 is not.
-        let bare = unbracketed(host)
-        let authority = bare.contains(":") ? "[\(bare)]:\(port)" : "\(bare):\(port)"
+        let authority = host.contains(":") ? "[\(host)]:\(port)" : "\(host):\(port)"
         let request = """
             GET \(path) HTTP/1.1\r
             Host: \(authority)\r
             User-Agent: punktfunk-apple\r
             Accept: */*\r
-            Connection: close\r
             \r
 
             """
         return Data(request.utf8)
     }
-
-    /// Saved hosts store bare addresses, but a user who pasted a bracketed IPv6 literal shouldn't
-    /// get an unresolvable endpoint out of it.
-    private static func unbracketed(_ host: String) -> String {
-        guard host.hasPrefix("["), host.hasSuffix("]"), host.count > 2 else { return host }
-        return String(host.dropFirst().dropLast())
-    }
 }
diff --git a/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift b/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift
index 84d789ab..cb71f517 100644
--- a/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift
+++ b/clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift
@@ -165,6 +165,138 @@ final class LibraryClientTests: XCTestCase {
         XCTAssertEqual([UInt8](response.body), png)
     }
 
+    // MARK: - Message framing (keep-alive)
+
+    // Connections are pooled and reused, so a response has to be delimited WITHOUT waiting for
+    // the peer to hang up. Getting this wrong either truncates a response or bleeds one response
+    // into the next, and both would be silent.
+
+    func testMessageLengthDelimitsContentLengthFraming() throws {
+        let complete = raw("HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhello")
+        XCTAssertEqual(try HTTPResponseParser.messageLength(in: complete), complete.count)
+        XCTAssertNil(try HTTPResponseParser.messageLength(
+            in: raw("HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhel")))
+    }
+
+    func testMessageLengthDelimitsChunkedFraming() throws {
+        let complete = raw("HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n5\r\nhello\r\n0\r\n\r\n")
+        XCTAssertEqual(try HTTPResponseParser.messageLength(in: complete), complete.count)
+        // Mid-chunk, and terminal chunk without its closing blank line.
+        XCTAssertNil(try HTTPResponseParser.messageLength(
+            in: raw("HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n5\r\nhel")))
+        XCTAssertNil(try HTTPResponseParser.messageLength(
+            in: raw("HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n5\r\nhello\r\n0\r\n")))
+        // Trailers belong to the message and must be consumed with it.
+        let trailered = raw("HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n"
+            + "3\r\nabc\r\n0\r\nX-Trailer: 1\r\n\r\n")
+        XCTAssertEqual(try HTTPResponseParser.messageLength(in: trailered), trailered.count)
+    }
+
+    func testMessageLengthIsNilWithoutFraming() throws {
+        // No Content-Length and not chunked ⇒ the body runs to EOF and the connection can't be
+        // reused. Partial header blocks are likewise "not yet".
+        XCTAssertNil(try HTTPResponseParser.messageLength(in: raw("HTTP/1.1 200 OK\r\n\r\nto-eof")))
+        XCTAssertNil(try HTTPResponseParser.messageLength(in: raw("HTTP/1.1 200 OK\r\nContent-Len")))
+    }
+
+    func testBackToBackResponsesSplitExactly() throws {
+        // The reuse case that matters: two responses arriving in one read.
+        let first = raw("HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhello")
+        let second = raw("HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nbye")
+        let both = first + second
+        XCTAssertEqual(try HTTPResponseParser.messageLength(in: both), first.count)
+        XCTAssertEqual(
+            String(decoding: try HTTPResponseParser.parse(both.prefix(first.count)).body,
+                   as: UTF8.self), "hello")
+        XCTAssertEqual(
+            String(decoding: try HTTPResponseParser.parse(both.dropFirst(first.count)).body,
+                   as: UTF8.self), "bye")
+    }
+
+    func testConnectionCloseIsDetected() throws {
+        let response = try HTTPResponseParser.parse(
+            raw("HTTP/1.1 200 OK\r\nConnection: close\r\nContent-Length: 0\r\n\r\n"))
+        XCTAssertTrue(response.wantsClose)
+        // HTTP/1.1 keeps the connection open unless told otherwise.
+        XCTAssertFalse(try HTTPResponseParser.parse(
+            raw("HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n")).wantsClose)
+    }
+
+    // MARK: - Art cache
+
+    private func temporaryCacheDirectory() -> URL {
+        URL(fileURLWithPath: NSTemporaryDirectory())
+            .appendingPathComponent("pf-art-test-\(UUID().uuidString)", isDirectory: true)
+    }
+
+    func testArtCacheRoundTripsBinaryAndSeparatesKeys() async throws {
+        let directory = temporaryCacheDirectory()
+        defer { try? FileManager.default.removeItem(at: directory) }
+        let cache = ArtCache(directory: directory)
+
+        let png = Data([0x89, 0x50, 0x4E, 0x47, 0x00, 0xFF, 0x0D, 0x0A])
+        let portrait = URL(string: "https://100.64.1.2:47990/api/v1/library/art/steam:570/portrait")!
+        let header = URL(string: "https://100.64.1.2:47990/api/v1/library/art/steam:570/header")!
+
+        var hit = await cache.data(for: portrait)
+        XCTAssertNil(hit, "cold cache must miss")
+        await cache.store(png, for: portrait)
+        hit = await cache.data(for: portrait)
+        XCTAssertEqual(hit, png, "posters are binary; the body must survive byte-for-byte")
+        // Sibling art of the same title must not collide.
+        let sibling = await cache.data(for: header)
+        XCTAssertNil(sibling)
+    }
+
+    func testArtCacheRefusesEmptyAndInlineData() async throws {
+        let directory = temporaryCacheDirectory()
+        defer { try? FileManager.default.removeItem(at: directory) }
+        let cache = ArtCache(directory: directory)
+
+        let empty = URL(string: "https://cdn.example.com/empty.jpg")!
+        await cache.store(Data(), for: empty)
+        let emptyHit = await cache.data(for: empty)
+        XCTAssertNil(emptyHit, "an empty body is not art")
+
+        let inline = URL(string: "data:image/png;base64,iVBORw0KGgo=")!
+        await cache.store(Data("x".utf8), for: inline)
+        let inlineHit = await cache.data(for: inline)
+        XCTAssertNil(inlineHit, "a data: URL is already inline — caching it is a pure loss")
+    }
+
+    func testArtCacheAgesEntriesOut() async throws {
+        let directory = temporaryCacheDirectory()
+        defer { try? FileManager.default.removeItem(at: directory) }
+        let cache = ArtCache(directory: directory, maxAge: 0.4)
+        let url = URL(string: "https://cdn.example.com/stale.jpg")!
+
+        await cache.store(Data("stale".utf8), for: url)
+        let fresh = await cache.data(for: url)
+        XCTAssertNotNil(fresh)
+        try await Task.sleep(nanoseconds: 700_000_000)
+        let expired = await cache.data(for: url)
+        XCTAssertNil(expired)
+    }
+
+    func testArtCacheEvictsLeastRecentlyUsedOverBudget() async throws {
+        let directory = temporaryCacheDirectory()
+        defer { try? FileManager.default.removeItem(at: directory) }
+        // Budget holds three of these; the fourth store must evict.
+        let cache = ArtCache(directory: directory, maxBytes: 300)
+        let blob = Data(repeating: 0x41, count: 100)
+        var urls: [URL] = []
+        for i in 0..<4 {
+            let url = URL(string: "https://cdn.example.com/blob\(i).jpg")!
+            urls.append(url)
+            await cache.store(blob, for: url)
+            try await Task.sleep(nanoseconds: 60_000_000) // distinct mtimes for LRU ordering
+        }
+        let evicted = await cache.data(for: urls[0])
+        XCTAssertNil(evicted, "the oldest entry should have been evicted")
+        let newest = await cache.data(for: urls[3])
+        XCTAssertEqual(newest, blob)
+    }
+
     func testBaseURLBracketsIPv6Only() {
         XCTAssertEqual(LibraryClient.baseURL(address: "192.168.1.70", port: 47990),
                        "https://192.168.1.70:47990")