Phase 6: Lüftersteuerung über privilegierten Helfer

Das Sicherheitsnetz kommt zuerst und liegt als reine Funktion vor — 17 Tests,
kein Hardwarezugriff nötig. Es sitzt im Helfer, nicht in der Oberfläche: die
kann abstürzen, hängen oder beendet sein, während die Lüfter auf einem festen
Wert stehen. Genau dafür ist es da.

Vier Regeln, nicht abschaltbar: nie unter das Firmware-Minimum, Rückfall auf
Automatik ab 95 °C, Rückfall wenn der Herzschlag fünf Sekunden ausbleibt,
Rückfall beim Beenden. Ohne lesbare Temperatur wird gar nicht gesteuert —
blind eine feste Drehzahl zu halten wäre die falsche Antwort auf fehlende
Information.

Die App sagt dem Helfer NICHT, wie warm es ist. Er misst selbst. Sonst hinge
das Netz an der Ehrlichkeit eines Prozesses, der abstürzen, hängen oder — bei
einer manipulierten Kopie — schlicht lügen kann. Der Herzschlag sagt nur "ich
lebe noch".

Der Helfer entscheidet jede Sekunde neu, nicht nur beim Setzen: nur so greifen
Wachhund und Temperaturwächter auch dann, wenn von der App nie wieder etwas
kommt. Geschrieben wird nur bei Änderung — jeder SMC-Schreibvorgang ist ein
Eingriff.

Der Schreibpfad existiert ausschließlich im Helfer, als eigene Kopie statt
geteilter Bibliothek. Was im App-Prozess nicht vorhanden ist, kann dort auch
nicht versehentlich aufgerufen werden.

XPC prüft die Signatur in BEIDE Richtungen. Ohne das könnte jedes Programm auf
dem Rechner die Lüfter eines root-Dienstes steuern — der Mach-Dienst ist
systemweit sichtbar.

Drei Fallstricke beim Einbetten, alle nachgemessen:

Xcode signiert Kommandozeilenprogramme unter dem Dateinamen. Der Helfer hieß
damit "OnyxHelper" statt com.scarriffleservices.onyx.helper, und die App hätte
ihren eigenen Helfer abgelehnt. Behoben über eine in die Binary eingebettete
Info.plist (CREATE_INFOPLIST_SECTION_IN_BINARY).

Der Build-Schritt läuft nach Xcodes Signatur; das Kopieren bricht das Siegel
des App-Bundles. Also wird zum Schluss neu signiert — mit denselben
Entitlements, sonst gingen App-Group, WeatherKit und die TCC-Berechtigungen
verloren.

Mit deklarierten outputFiles übersprang Xcode den Schritt, obwohl sich das
Programm geändert hatte.

Geprüft: App-Siegel gültig (deep), beide Signaturanforderungen erfüllt,
alle sieben Entitlements erhalten. 162 Tests grün.

Packages/OnyxKit/Sources/OnyxHelperProtocol/FanSafety.swift

@@ -0,0 +1,80 @@
+import Foundation
+
+/// Der von der Firmware erlaubte Drehzahlbereich eines Lüfters.
+public struct FanLimits: Equatable, Sendable, Codable {
+    public let minimum: Double
+    public let maximum: Double
+
+    public init(minimum: Double, maximum: Double) {
+        self.minimum = minimum
+        self.maximum = maximum
+    }
+
+    /// Ob die Werte überhaupt brauchbar sind. Nicht lesbare Keys ergeben Nullen.
+    public var isUsable: Bool { minimum > 0 && maximum > minimum }
+}
+
+public struct FanRequest: Equatable, Sendable, Codable {
+    public let targetRPM: Double
+    public init(targetRPM: Double) { self.targetRPM = targetRPM }
+}
+
+public enum FanDecision: Equatable, Sendable {
+    case manual(rpm: Double)
+    case automatic(reason: AutomaticReason)
+
+    public enum AutomaticReason: String, Equatable, Sendable {
+        /// Niemand will etwas anderes.
+        case noRequest
+        /// Die App hat sich zu lange nicht gemeldet.
+        case watchdog
+        /// Es ist zu heiß für eine feste Drehzahl.
+        case temperature
+        /// Ohne Temperaturmesswert lässt sich Sicherheit nicht beurteilen.
+        case noTemperature
+        /// Der erlaubte Bereich ist unbekannt.
+        case unknownLimits
+    }
+}
+
+/// Entscheidet, ob eine angeforderte Drehzahl gesetzt werden darf.
+///
+/// Diese Regeln sind **nicht abschaltbar** und liegen im Helfer, nicht in der
+/// Oberfläche. Die Oberfläche kann abstürzen, eingefroren oder beendet sein,
+/// während die Lüfter auf einem festen Wert stehen — genau dafür gibt es das
+/// Netz. Als reine Funktion ist es vollständig prüfbar, ohne Hardware.
+public enum FanSafety {
+
+    /// Meldet sich die App länger nicht, übernimmt die Automatik.
+    public static let watchdogTimeout: TimeInterval = 5
+
+    /// Ab hier zählt nur noch Kühlung. Apple Silicon drosselt in dieser Gegend
+    /// von selbst; eine festgenagelte Drehzahl verschlimmert die Lage, weil sie
+    /// nicht nachregelt.
+    public static let criticalCelsius: Double = 95
+
+    public static func decide(request: FanRequest?,
+                              lastHeartbeat: Date,
+                              now: Date,
+                              hottestCelsius: Double?,
+                              limits: FanLimits) -> FanDecision {
+        // Rangfolge: erst die Gründe, die Schaden verhindern, dann der Wunsch.
+        guard let request else { return .automatic(reason: .noRequest) }
+
+        guard let hottest = hottestCelsius else {
+            // Ohne Temperatur lässt sich nicht beurteilen, ob eine feste
+            // Drehzahl gerade gefährlich ist. Blind weiterdrehen wäre falsch.
+            return .automatic(reason: .noTemperature)
+        }
+        guard hottest < criticalCelsius else { return .automatic(reason: .temperature) }
+        guard now.timeIntervalSince(lastHeartbeat) <= watchdogTimeout else {
+            return .automatic(reason: .watchdog)
+        }
+        guard limits.isUsable else { return .automatic(reason: .unknownLimits) }
+
+        // Nie unter das Firmware-Minimum: ein Lüfter, der langsamer läuft als
+        // vorgesehen, kann den Rechner überhitzen, ohne dass die Automatik
+        // eingreift — die ist ja gerade abgeschaltet.
+        return .manual(rpm: min(max(request.targetRPM, limits.minimum), limits.maximum))
+    }
+}

Packages/OnyxKit/Sources/OnyxHelperProtocol/HelperProtocol.swift

@@ -0,0 +1,83 @@
+import Foundation
+
+/// Die Schnittstelle zwischen App und privilegiertem Helfer.
+///
+/// **Die App sagt dem Helfer nicht, wie warm es ist.** Der Helfer misst selbst.
+/// Andernfalls hinge das Sicherheitsnetz an der Ehrlichkeit eines Prozesses,
+/// der abstürzen, hängen oder — bei einer manipulierten Kopie — schlicht lügen
+/// kann. Der Herzschlag sagt deshalb nur „ich lebe noch", nichts weiter.
+@objc public protocol OnyxHelperProtocol {
+
+    /// Version des Helfers. Läuft nach einem App-Update noch die alte, muss sie
+    /// ersetzt werden — sonst passen die Aufrufe nicht mehr zusammen.
+    func version(reply: @escaping (String) -> Void)
+
+    /// Aktueller Zustand aller Lüfter, als JSON-kodierter ``FanStatus``.
+    ///
+    /// JSON statt eines eigenen Typs: `NSSecureCoding` über XPC verlangt
+    /// registrierte Klassen auf beiden Seiten, und dafür ist die Datenmenge
+    /// hier zu klein.
+    func fanStatus(reply: @escaping (Data?) -> Void)
+
+    /// Setzt eine Wunschdrehzahl. Der Helfer prüft sie gegen sein
+    /// Sicherheitsnetz und kann sie begrenzen oder ablehnen.
+    func setFan(index: Int, targetRPM: Double, reply: @escaping (Data?) -> Void)
+
+    /// Zurück zur Automatik.
+    func setFanAutomatic(index: Int, reply: @escaping (Data?) -> Void)
+
+    /// „Ich lebe noch." Bleibt er aus, fallen alle Lüfter auf Automatik zurück.
+    func heartbeat(reply: @escaping (Bool) -> Void)
+}
+
+/// Was der Helfer über einen Lüfter berichtet.
+public struct FanStatus: Codable, Equatable, Sendable {
+    public let index: Int
+    public let currentRPM: Double
+    public let targetRPM: Double
+    public let limits: FanLimits
+    public let isManual: Bool
+    /// Warum gerade die Automatik läuft — `nil` im manuellen Betrieb.
+    public let automaticReason: String?
+
+    public init(index: Int, currentRPM: Double, targetRPM: Double, limits: FanLimits,
+                isManual: Bool, automaticReason: String?) {
+        self.index = index
+        self.currentRPM = currentRPM
+        self.targetRPM = targetRPM
+        self.limits = limits
+        self.isManual = isManual
+        self.automaticReason = automaticReason
+    }
+}
+
+public struct FanStatusReport: Codable, Equatable, Sendable {
+    public let fans: [FanStatus]
+    public let hottestCelsius: Double?
+    public let helperVersion: String
+
+    public init(fans: [FanStatus], hottestCelsius: Double?, helperVersion: String) {
+        self.fans = fans
+        self.hottestCelsius = hottestCelsius
+        self.helperVersion = helperVersion
+    }
+}
+
+public enum OnyxHelper {
+    /// Muss zum Namen der Plist unter `Contents/Library/LaunchDaemons` passen.
+    public static let machServiceName = "com.scarriffleservices.onyx.helper"
+    public static let version = "1"
+
+    /// Nur ein Prozess mit exakt dieser Signatur darf mit dem Helfer sprechen.
+    ///
+    /// Ohne diese Prüfung könnte **jedes** Programm auf dem Rechner die Lüfter
+    /// eines root-Dienstes steuern — der Mach-Dienst ist systemweit sichtbar.
+    public static let clientRequirement =
+        "anchor apple generic and identifier \"com.scarriffleservices.onyx\" "
+        + "and certificate leaf[subject.OU] = \"PP34X97WS3\""
+
+    /// Und die App spricht nur mit einem Helfer, der ebenso signiert ist.
+    public static let helperRequirement =
+        "anchor apple generic and identifier \"com.scarriffleservices.onyx.helper\" "
+        + "and certificate leaf[subject.OU] = \"PP34X97WS3\""
+}