PROTOCOL NOTES / 12
19 · Apple device joins over Wi-Fi Aware pairing and advert discovery
Participants: Rider, Apple, Member, Organizer
Implemented software · Tested on hosts and emulators only · Physical qualification pending
Starting state
Apple device has imported an invitation of format version 3 (joining) and holds no cached advertisement of the member. A lobby member with Wi-Fi Aware (an Apple device or a NAN Pairing capable Android phone) publishes the fixed service _rideweave._tcp; the two devices are not yet paired. Apple Wi-Fi Aware discovery carries no RideWeave advertisement.
Ordered events
- Rider → Apple
Import the invitation of format version 3 and open the lobby
- Apple → Member
System pairing UI pairs the two devices for the fixed service
- Apple → Member
Network framework TCP to the paired publisher, which has no cached advertisement, TLS without an expected identity, greeting transportVersion 4 linkKind aware with announced UDP port
- Apple → Member
hello with ride, name and token
- Member → Apple
advert carrying the signed advertisement version 3 with capability flags, root and path
- Apple → Apple
Structural checks and the key against the TLS peer, then route checks, then use it as discovery on this link's channel
- Apple → Organizer
Signed join with capabilities, relayed by the member
- Organizer → Apple
Approve and publish the roster with member capabilities, relayed
- Apple → Rider
Lobby shows paired, missing, not possible or not needed for each member and offers only the pairings connectivity needs, Apple members first
Fields and messages
Invitation v 3; greeting transportVersion 4, linkKind aware, mediaPort, outgoing true at the Apple device, attempt 0; advert.advertisement version 3 (capability bits 0 Wi-Fi Aware child capacity, 1 Apple, 2 Wi-Fi Aware, 3 NAN Pairing, 4-7 BLE); join.capabilities; roster member capabilities.
Authorization and invariants
The advert passes the structural checks and its raw public key hashes to the TLS peer ID, otherwise the link closes; a serial not above the last one received on the link is ignored; a path containing the receiver only excludes the sender as a parent candidate. A paired device of another ride is refused at hello. Pairing grants no admission, membership or media authority, and pairing state never appears on the wire. The first advert of an Apple-initiated link binds the identity accepted at TLS. When the member is an Apple device that connected at the same time, the link opened by the higher peer ID is closed once neither link holds a forwarding role or takes part in a handoff transaction.
Timers
TLS and greeting 5 s; hello 5 s; advert after hello and at every re-signing (1 s while unsettled, 3 s when settled, at once on a route-shape or capability change); join retried every second while waiting for approval; an Apple-opened link that has not become useful is closed within 10 s, an admission link counting as useful while admission is open.
Resource lifetime
The platform pairing persists across rides and is reused; its binding to a RideWeave identity is local adapter state. Ride, token, roster and link state are ephemeral.
What the rider sees
Native system pairing screens; the lobby shows per-member pairing coverage and recommends only the pairings connectivity needs (each Apple member with up to two Wi-Fi Aware members, Apple first); before sealing the organizer sees a warning if the roster's capability graph, with leaves removed, leaves some riders unable to hear each other.
Failure branches
A declined or removed pairing stays missing and BLE remains possible; an Android phone without NAN Pairing never connects to an Apple device over Wi-Fi Aware; an advert that fails a structural check or whose key differs from the TLS peer closes the link; a greeting with another transport version or linkKind closes the link; an invitation of an older format is refused with update guidance; a publisher whose cached advertisement showed no child capacity is not connected.
Resulting state
Apple device is an approved lobby member linked over Wi-Fi Aware (link kind aware) to the member; it has learned the member's route from advert; its roster record carries its capabilities; its lobby shows pairing coverage and recommends only the pairings connectivity needs.
Evidence boundary
Implemented software; host, Swift package and JVM tests only. Host tests cover invitation format 3, advertisement version 3 and update guidance, Apple capability flags and child capacity, the advert identity check and lobby pairing plans; Swift package tests cover the useful-link rule, the publisher cache and two engines over in-memory Swift connections; JVM tests cover NAN Pairing capability. The Wi-Fi Aware adapter has not run between devices, and Apple to Android Wi-Fi Aware needs a NAN Pairing capable Android phone; both are physically unqualified.
Authority: RWCP v2 reviewed scenario catalogue, scenario 19. Public examples are synthetic. This guide is maintained against the private implementation; it does not imply access to its source.