feat(apple): adapt the macOS client to ABI v2 — client identity + SPAKE2 PIN pairing

The pairing/renegotiation batch bumped the punktfunk/1 ABI to v2 and the host now
hard-rejects v1 Hellos (m3.rs), so streaming from the Mac was dead until the bundled
PunktfunkCore.xcframework is rebuilt — it is gitignored, so that is a per-checkout step:
bash scripts/build-xcframework.sh. The Swift wrapper itself was already adapted upstream;
this lands the app on top of it.

- ClientIdentityStore: persistent client identity in the login Keychain, presented on
  every connect so paired hosts recognize this Mac. Keychain access failure throws
  instead of regenerating (a fresh identity would silently un-pair this Mac from every
  --require-pairing host); a lost first-run race resolves toward the stored identity;
  pairing uses the strict loadForPairing() so a memory-only identity can't strand a
  ceremony.
- PairSheet: the SPAKE2 PIN ceremony, reachable from a host card's context menu and from
  the trust prompt's "Pair with PIN instead…" (which drops the live session first — the
  host's accept loop is sequential). Success pins the verified fingerprint and connects;
  an in-flight ceremony self-discards when the sheet is dismissed, so a late success
  can't pin + auto-connect behind the user's back. Wrong PIN and Keychain failures get
  distinct, actionable error text.
- Tests: identity unit tests; the full pairing ceremony + --require-pairing gate on
  loopback (test-loopback.sh arms a second host, parses its PIN from the log, and gives
  both hosts throwaway config homes — no more writes to the real ~/.config/punktfunk);
  remote pairing + pinned stream over the LAN (PUNKTFUNK_REMOTE_PIN, _PORT).

Validated live against the box: SPAKE2 ceremony with the host's arming PIN → verified
fingerprint → pinned + identified 720p60 session (host persisted the client identity);
first light 60/60 AUs decoded to pixels; vkcube on glass through the app.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

clients/apple/Tests/PunktfunkKitTests/IdentityTests.swift

@@ -0,0 +1,36 @@
+// Client identity generation through the ABI (punktfunk_generate_identity): the PEM pair
+// hosts use to recognize a paired client. Pure local crypto — no host needed.
+
+import XCTest
+@testable import PunktfunkKit
+
+final class IdentityTests: XCTestCase {
+    func testGenerateIdentityYieldsDistinctPEMPairs() throws {
+        let a = try generateIdentity()
+        let b = try generateIdentity()
+
+        XCTAssertTrue(a.certPEM.contains("BEGIN CERTIFICATE"), "cert is PEM")
+        XCTAssertTrue(a.keyPEM.contains("PRIVATE KEY"), "key is PEM")
+        XCTAssertTrue(a.certPEM.hasSuffix("\n") || a.certPEM.contains("END CERTIFICATE"))
+
+        // Each call mints a fresh keypair — identical output would mean a broken RNG.
+        XCTAssertNotEqual(a.certPEM, b.certPEM)
+        XCTAssertNotEqual(a.keyPEM, b.keyPEM)
+    }
+
+    func testPairAgainstNothingFailsCleanly() {
+        // Nothing listens on this port; the ceremony must throw within its timeout, and
+        // must not report .wrongPIN (no SPAKE2 exchange ever happened).
+        do {
+            let identity = try generateIdentity()
+            _ = try pair(
+                host: "127.0.0.1", port: 9, identity: identity,
+                pin: "0000", name: "test", timeoutMs: 2000)
+            XCTFail("expected pair() against a dead port to throw")
+        } catch PunktfunkClientError.wrongPIN {
+            XCTFail("dead port must not look like a wrong PIN")
+        } catch {
+            // any other error is the correct outcome
+        }
+    }
+}

clients/apple/Tests/PunktfunkKitTests/LoopbackIntegrationTests.swift

@@ -62,4 +62,59 @@ final class LoopbackIntegrationTests: XCTestCase {
                 host: "127.0.0.1", port: 9, width: 640, height: 480, refreshHz: 30,
                 timeoutMs: 2000))
     }
+
+    /// The PIN pairing ceremony + the --require-pairing gate through the Swift wrapper:
+    /// anonymous rejection, the single wrong-PIN online guess, the real ceremony, and a
+    /// paired + pinned session. Driven by test-loopback.sh, which arms a second host with
+    /// --require-pairing and parses its random PIN out of the log.
+    func testPairingCeremonyAndRequirePairingGate() throws {
+        let env = ProcessInfo.processInfo.environment
+        guard let portStr = env["PUNKTFUNK_PAIRING_PORT"], let port = UInt16(portStr),
+              let pin = env["PUNKTFUNK_PAIRING_PIN"]
+        else {
+            throw XCTSkip("needs an armed m3-host — use clients/apple/test-loopback.sh")
+        }
+
+        let identity = try generateIdentity()
+
+        // 1. Unpaired clients don't get sessions from a --require-pairing host.
+        XCTAssertThrowsError(
+            try PunktfunkConnection(
+                host: "127.0.0.1", port: port, width: 1280, height: 720, refreshHz: 60,
+                identity: identity, timeoutMs: 5000),
+            "unpaired client must be rejected")
+
+        // 2. A wrong PIN is exactly one failed online guess — distinguishable from
+        //    transport errors so the UI can say "try again".
+        XCTAssertThrowsError(
+            try pair(
+                host: "127.0.0.1", port: port, identity: identity,
+                pin: pin == "0000" ? "9999" : "0000", name: "wrong-pin", timeoutMs: 5000)
+        ) { error in
+            guard case PunktfunkClientError.wrongPIN = error else {
+                return XCTFail("expected .wrongPIN, got \(error)")
+            }
+        }
+
+        // 3. The real ceremony (after the host's 2 s pairing cooldown).
+        Thread.sleep(forTimeInterval: 2.2)
+        let fingerprint = try pair(
+            host: "127.0.0.1", port: port, identity: identity,
+            pin: pin, name: "loopback-test", timeoutMs: 5000)
+        XCTAssertEqual(fingerprint.count, 32)
+
+        // 4. Paired + pinned: the same identity now gets a session, and the ceremony's
+        //    fingerprint matches the certificate the host actually serves.
+        let conn = try PunktfunkConnection(
+            host: "127.0.0.1", port: port, width: 1280, height: 720, refreshHz: 60,
+            pinSHA256: fingerprint, identity: identity, timeoutMs: 5000)
+        XCTAssertEqual(conn.hostFingerprint, fingerprint)
+        var got = 0
+        let deadline = Date().addingTimeInterval(15)
+        while got < 5, Date() < deadline {
+            if try conn.nextAU(timeoutMs: 2000) != nil { got += 1 }
+        }
+        conn.close()
+        XCTAssertGreaterThanOrEqual(got, 5, "paired session must stream")
+    }
 }

clients/apple/Tests/PunktfunkKitTests/RemoteFirstLightTests.swift

@@ -15,15 +15,49 @@ import XCTest
 @testable import PunktfunkKit
 
 final class RemoteFirstLightTests: XCTestCase {
+    /// The pairing ceremony over the real LAN, exactly as the app runs it: fresh identity,
+    /// SPAKE2 with the host's arming PIN, then a pinned + identified session. Needs the
+    /// host armed (--allow-pairing) and its logged PIN in PUNKTFUNK_REMOTE_PIN. Heads-up:
+    /// every run durably adds one throwaway "remote-test" identity to the host's
+    /// ~/.config/punktfunk/punktfunk1-paired.json — prune those entries at will.
+    func testRemotePairingThenPinnedStream() throws {
+        let env = ProcessInfo.processInfo.environment
+        guard let host = env["PUNKTFUNK_REMOTE_HOST"], let pin = env["PUNKTFUNK_REMOTE_PIN"]
+        else {
+            throw XCTSkip("set PUNKTFUNK_REMOTE_HOST + PUNKTFUNK_REMOTE_PIN "
+                + "(host armed with --allow-pairing)")
+        }
+        let port = env["PUNKTFUNK_REMOTE_PORT"].flatMap(UInt16.init) ?? 9777
+
+        let identity = try generateIdentity()
+        let fingerprint = try pair(
+            host: host, port: port, identity: identity, pin: pin, name: "remote-test")
+        XCTAssertEqual(fingerprint.count, 32)
+
+        let conn = try PunktfunkConnection(
+            host: host, port: port, width: 1280, height: 720, refreshHz: 60,
+            pinSHA256: fingerprint, identity: identity)
+        defer { conn.close() }
+        XCTAssertEqual(conn.hostFingerprint, fingerprint)
+        var got = 0
+        let deadline = Date().addingTimeInterval(20)
+        while got < 10, Date() < deadline {
+            if try conn.nextAU(timeoutMs: 2000) != nil { got += 1 }
+        }
+        XCTAssertGreaterThanOrEqual(got, 10, "paired + pinned session must stream")
+    }
+
     func testRemoteStreamDecodesToPixels() throws {
-        guard let host = ProcessInfo.processInfo.environment["PUNKTFUNK_REMOTE_HOST"] else {
+        let env = ProcessInfo.processInfo.environment
+        guard let host = env["PUNKTFUNK_REMOTE_HOST"] else {
             throw XCTSkip("set PUNKTFUNK_REMOTE_HOST (and start m3-host --source virtual there)")
         }
+        let port = env["PUNKTFUNK_REMOTE_PORT"].flatMap(UInt16.init) ?? 9777
         let width: UInt32 = 1280
         let height: UInt32 = 720
 
         let conn = try PunktfunkConnection(
-            host: host, width: width, height: height, refreshHz: 60)
+            host: host, port: port, width: width, height: height, refreshHz: 60)
         defer { conn.close() }
         XCTAssertEqual(conn.width, width)
         XCTAssertEqual(conn.height, height)