Apple HomeKit (HAP) Bridge
Relevant source files
The following files were used as context for generating this wiki page:
The Apple HomeKit (HAP) Bridge provides a bounded, fail-closed HomeKit Accessory Protocol (HAP) IP server for the Homecore runtime. It allows WiFi-based sensing data, such as motion and occupancy, to be exposed to Apple Home controllers through encrypted control sessions and mDNS discovery.
This component implements HAP R2 cryptographic pairing and transport boundaries. It wires TCP handling, pairing records, and the _hap._tcp mDNS lifecycle into the Homecore server environment.
Sources: v2/crates/homecore-hap/README.md, harness/homecore/src/capabilities.js:106-113
Architecture and Components
The HAP Bridge architecture consists of a central bridge accessory that manages communication between the Homecore state and Apple Home controllers. It utilizes a PairingStore for security credentials and an MdnsSdAdvertiser for network discovery.
Component Overview
| Component | Description |
|---|---|
| HapBridge | Manages the bridge accessory identity and child accessories. |
| PairingStore | Handles persisted Ed25519 keys, SRP verifiers, and controller records. |
| HapServer | Manages TCP connections, encryption, and HAP record framing. |
| MdnsSdAdvertiser | Handles _hap._tcp discovery and service feature (sf) flags. |
| RuViewMotion | A specialized accessory exposing Motion, Occupancy, and Anomaly services. |
Sources: v2/crates/homecore-hap/README.md, scripts/hap-test-sensor.py:64-75, harness/homecore/src/capabilities.js:113-116
System Data Flow
The following diagram illustrates the lifecycle from provisioning to live state updates.
The HAP Bridge remains inaccessible until Pair-Verify succeeds. After verification, all traffic uses HAP records with 64-bit monotonic nonces.
Sources: v2/crates/homecore-hap/README.md, harness/homecore/src/capabilities.js:108-112
Security and Cryptography
The bridge implements a strict "fail-closed" security posture. Any failure in authentication, replay detection, or record size results in the immediate closure of the TCP connection without providing an oracle response to the client.
Cryptographic Primitives
- Pair-Setup (M1-M6): RFC 5054 3072-bit group with SHA-512 and SRP verifiers.
- Pair-Verify (M1-M4): Ephemeral X25519 and Ed25519 transcript verification.
- Transport Encryption: ChaCha20-Poly1305 with HKDF-SHA512.
- Storage: Versioned JSON stores with atomic replacement and Unix mode
0600permissions.
Sources: v2/crates/homecore-hap/README.md, harness/homecore/src/capabilities.js:112
Service Implementation
The bridge maps RuView sensing primitives to standard HomeKit services. A single accessory often carries multiple services to provide comprehensive spatial data.
HAP Service Mapping
Motion Sensor:* Tracks short-window movement (motion_score).
- Occupancy Sensor: Tracks sustained presence via rolling averages.
- Programmable Switch: Fires for "Unrecognized Activity Patterns" (BFLD anomaly detection).
Sources: scripts/hap-test-sensor.py:64-90, v2/crates/homecore-hap/README.md
Integration and Provisioning
The HAP Bridge is feature-gated and disabled by default. It requires explicit network and durable pairing configuration to operate.
Server Startup Procedure
- Initialize
PairingStorefrom a security JSON file. - Retrieve the
SetupCodeduring the first provisioning session. - Construct the
HapServiceRecordandHapBridge. - Start the
HapServerwith a specific IP address and port (default 51826). - Feed
StateChangedevents from the Homecore event bus to the bridge.
let provisioned = PairingStore::load_or_create("/var/lib/homecore-hap/security.json")?;
let pairings = Arc::new(provisioned.store);
let record = HapServiceRecord::bridge("HOMECORE Bridge", 51826, pairings.accessory_id()?);
let server = start_server(HapServerConfig::default(), bridge.clone(), pairings, advertiser).await?;
Sources: v2/crates/homecore-hap/README.md, harness/homecore/src/capabilities.js:118-120
Validation and Limitations
The HAP implementation is protocol-level (HAP R2) and does not currently claim Apple MFi certification.
- Verified: SRP session-key vectors, complete Pair-Setup/Verify ceremonies, and atomic restart behavior.
- Limitations:
- Transient/split Pair-Setup flags are rejected.
- Writable characteristics and resource endpoints are not implemented.
- Persistent AID/IID allocation is currently unstable.
- Hardware-backed key stores (HSM) are not yet integrated.
Sources: v2/crates/homecore-hap/README.md, harness/homecore/src/capabilities.js:121-125, harness/ruview/src/guidance.js:156-160