XPC Helper Service
Relevant source files
The following files were used as context for generating this wiki page:
The XPC Helper Service is a privileged background component of the Buddi application designed to perform system-level operations that require specific entitlements or elevated permissions. It primarily handles macOS accessibility authorization and hardware control for screen and keyboard brightness. By offloading these tasks to a separate process, the main Buddi application maintains a cleaner security profile while still providing utility features like HUD replacements for volume and brightness.
The service is identified by the bundle identifier com.talkvalue.buddi.XPCHelper. It utilizes the NSXPCConnection framework to communicate with the main application, ensuring type-safe method calls through a shared Swift protocol.
Sources: BuddiXPCHelper/BuddiXPCHelperProtocol.swift:11-13, buddi/XPCHelperClient/XPCHelperClient.swift:7-9, buddi/buddiApp.swift:55-58
System Architecture
The XPC architecture follows a client-server model where the XPCHelperClient within the main app acts as a proxy for the BuddiXPCHelper service.
Communication Flow
- Client Initialization: The
XPCHelperClientestablishes anNSXPCConnectionusing the service name. - Protocol Vending: The helper service vends an object conforming to
BuddiXPCHelperProtocol. - Asynchronous Execution: All calls from the client to the helper are asynchronous, utilizing completion handlers (reply blocks) to return data or status updates.
The diagram shows the typical flow for requesting system permissions through the helper.
Sources: BuddiXPCHelper/BuddiXPCHelperProtocol.swift:27-46, buddi/XPCHelperClient/XPCHelperClient.swift:23-44
Key Components
BuddiXPCHelper
The core implementation of the service. It utilizes private and public macOS frameworks to interact with hardware and system settings.
- KeyboardBrightnessClient: An internal class that dynamically loads
CoreBrightness.frameworkto get and set keyboard backlight levels. - DisplayServices Integration: Uses
dlopenanddlsymto access the privateDisplayServices.frameworkfor screen brightness control. - IOKit Fallback: Provides a secondary path for brightness control via
IOServiceMatching("IODisplayConnect")if private frameworks are unavailable.
Sources: BuddiXPCHelper/BuddiXPCHelper.swift:11-14, BuddiXPCHelper/BuddiXPCHelper.swift:40-45, BuddiXPCHelper/BuddiXPCHelper.swift:101-110
XPCHelperClient
A singleton manager in the main application that abstracts XPC connection details and provides a modern Swift async/await interface for the app's UI components.
Sources: buddi/XPCHelperClient/XPCHelperClient.swift:5-10
Functional Areas
Accessibility Authorization
The service manages the application's trusted status within macOS. It provides methods to check current status, request access via a system prompt, and monitor changes.
Sources: BuddiXPCHelper/BuddiXPCHelper.swift:14-36
Hardware Control
The service provides granular control over device hardware, which is used for Buddi's custom HUD overlays.
| Feature | Method | Frameworks Used |
|---|---|---|
| Keyboard Brightness | setKeyboardBrightness(_:with:) | CoreBrightness (Private) |
| Screen Brightness | setScreenBrightness(_:with:) | DisplayServices (Private), IOKit |
| Status Check | isAccessibilityAuthorized(with:) | ApplicationServices (AXIsProcessTrusted) |
| Sources: BuddiXPCHelper/BuddiXPCHelperProtocol.swift:14-25, BuddiXPCHelper/BuddiXPCHelper.swift:40-42, BuddiXPCHelper/BuddiXPCHelper.swift:115-125 |
Monitoring and Notifications
The XPCHelperClient includes a background monitoring task that checks accessibility status every 3 seconds. When a change is detected, it broadcasts a Notification.Name.accessibilityAuthorizationChanged event.
Sources: buddi/XPCHelperClient/XPCHelperClient.swift:63-75, buddi/XPCHelperClient/XPCHelperClient.swift:189-191
Implementation Details
Keyboard Brightness Logic
The helper uses a specialized KeyboardBrightnessClient that identifies the keyboard hardware using a hardcoded ID (1) and invokes selectors on the private KeyboardBrightnessClient class.
Sources: BuddiXPCHelper/BuddiXPCHelper.swift:41-55
Service Protocol
@objc protocol BuddiXPCHelperProtocol {
func isAccessibilityAuthorized(with reply: @escaping (Bool) -> Void)
func requestAccessibilityAuthorization()
func ensureAccessibilityAuthorization(_ promptIfNeeded: Bool, with reply: @escaping (Bool) -> Void)
func isKeyboardBrightnessAvailable(with reply: @escaping (Bool) -> Void)
func currentKeyboardBrightness(with reply: @escaping (NSNumber?) -> Void)
func setKeyboardBrightness(_ value: Float, with reply: @escaping (Bool) -> Void)
func isScreenBrightnessAvailable(with reply: @escaping (Bool) -> Void)
func currentScreenBrightness(with reply: @escaping (NSNumber?) -> Void)
func setScreenBrightness(_ value: Float, with reply: @escaping (Bool) -> Void)
}
Sources: buddi/XPCHelperClient/BuddiXPCHelperProtocol.swift:11-23
Summary
The XPC Helper Service is a critical bridge between Buddi's high-level UI and the low-level macOS system APIs. By centralizing hardware access and permission management in a dedicated service, the project ensures robust operation of HUD features and provides a consistent mechanism for handling macOS privacy requirements.