Skip to content

feat(protocol): a ble-to-wi-fi fast link between devices that meet over bluetooth (adr 0038) - #756

Merged
bahdotsh merged 82 commits into
mainfrom
feat/ble-to-wifi-fast-link
Nov 17, 2026
Merged

bahdotsh merged 82 commits into
mainfrom
feat/ble-to-wifi-fast-link

Conversation

@mizanxali

Copy link
Copy Markdown
Member

Summary

Adds the fast link (ADR 0038): two devices that meet over Bluetooth LE and share a confirmed MLS session bring up a Wi-Fi network between them, and the stream over it fills the wifi_direct peer-stream slot. Transfers move onto it on their own and back to Bluetooth when it ends.

  • Android hosts a Wi-Fi Direct group with engine-chosen credentials and admits only the invited peer. An iPhone joins with NEHotspotConfiguration (joinOnce), after a system prompt; an Android can also join.
  • Credentials only travel sealed. The new __FAST_LINK__ frames (request, offer, close) are sent only inside the 1:1 session with the strict encryptor, once, over a live direct link (Bluetooth first), never queued, relayed or acknowledged. Frames found anywhere else, including ones that waited in the pending-decryption queue, are consumed and dropped.
  • A pure state machine (crates/offline-protocol/src/fast_link.rs): no clock, randomness or engine, three drained queues (frames, events, platform directives). That lets two-ended tests drive both sides through every transition.
  • Abuse bounds, each tied to the failure it prevents:
    • a decline pause, and the same pause after two unanswered unasked offers;
    • a host backoff after two hosted links that carried nothing;
    • refusal of late offers, an offer that names the network the joiner is already on, or a host address that is already its Wi-Fi gateway;
    • a 60 s idle limit that only bodies of 16 KiB or more reset.
  • Platform driver calls (UDL): wifi_direct_set_fast_link_roles, wifi_direct_next_fast_link_directive, wifi_direct_fast_link_hosting, wifi_direct_fast_link_ended. Application calls request_fast_link / close_fast_link, plus a fast_link_changed event. wifiDirect.fastLink (any / requestedOnly / off) sets how far an app takes part.
  • Capability: link_versions: [1] in the key package, which is additive and left out when empty.
  • Peer-stream slot: a 512 KiB window (16 chunks of 32 KiB) on every peer-stream carrier, bounded by a compile-time check against the ratchet tolerance.

Docs: ADR 0038, docs/state-machines/fast-link.md, docs/spec/control-messages.md (frame family, reasons, bounds), threat model R34, docs/mobile-permissions.md, docs/spec/stream-framing.md, CHANGELOG.

Measured on two phones (iPhone 16, Samsung Galaxy M17 on Android 16)

Result
Request to the iPhone's join prompt about 0.4 s
Join tapped to link up 10 to 11.4 s (about 10 s of it is iOS's own scan and association)
1 MiB, Android to iPhone 2.0 to 2.6 s on the link, against 197.7 s over Bluetooth
iPhone app sent to the background link ends on both sides in about 1.1 s
iPhone-initiated request (the Android hosts under the iPhone's id) up in 11.0 s, 1 MiB in 2.04 s
Android killed while hosting its leftover group is removed on the next start
Both phones meet over a shared home network while an offer is pending both sides end superseded, no false up, the home-network stream carries on

Integration notes

  • iOS needs the Hotspot Configuration entitlement and local-network permission. No location permission and no Access Wi-Fi Information entitlement: the iPhone checks it is on the group by its Wi-Fi gateway being the offered host, since NEHotspotNetwork.fetchCurrent names no joinOnce network without location permission.
  • Android needs NEARBY_WIFI_DEVICES (fine location below Android 13). A fast link and Wi-Fi Direct group formation share the one group a device can own.
  • iOS shows its join prompt on every join and takes the phone off its own Wi-Fi while the link lasts. With the default fastLink: 'any', a session peer can start a link, which shows that prompt without the app asking; requestedOnly stops that.
  • Flutter gets requestFastLink / closeFastLink too, because the shared bridge has to match the Flutter method list.

Known limits and follow-ups

  • An idle or iPhone-ended close is logged as lost on the host: the close frame goes out over the stream being torn down. Sending closes over Bluetooth would fix it.
  • A peer's superseded that arrives before this device has proved the other stream at all is still counted against the peer (a Bluetooth frame has to beat the stream's preamble).
  • After the join, iOS adopts a stream whose path has no gateway (the pre-DHCP stream over the group). On a home network that reports no gateway, a stream there would be adopted too.
  • Not run on devices: an Android 12 or earlier host (it advertises the LAN service on the group interface, which the iOS adoption rule exists for), Android joining Android, and screen lock.
  • If the link is superseded while the iOS prompt is on screen and the user taps Join, the phone joins the group for a few seconds before leaving it. Apps cannot dismiss that prompt.
  • The 512 KiB window applies to every peer-stream carrier, not only the fast link, and could be split into its own PR.

Related issues

None.

Type of change

  • feat new feature
  • docs documentation
  • test tests

Checklist

  • cargo fmt --all -- --check passes
  • cargo clippy --workspace -- -D warnings passes
  • cargo test --workspace passes
  • cargo-deny is satisfied (no new dependencies)
  • Commits follow Conventional Commits
  • Docs / CHANGELOG.md updated
  • No new unsafe in core crates
  • UDL changed: all five bindings regenerated together; the C dispatcher, the C# tables and the Python local API table are current

Test plan

  • 59 fast-link tests (cargo test -p offline-protocol --lib fast_link): the state machine driven from both ends, and two engines over real MLS (sealing, ephemeral sends, Bluetooth preference, blocking, stop and pause, transfers failing with the link, superseded)
  • Bridge source guards in offline-protocol-uniffi (tokens match the engine's, no directive logged whole, announce order, gateway checks, leftover-group record)
  • iOS app and Android app build against the branch
  • Device runs on an iPhone 16 and a Samsung Galaxy M17 (table above)
  • Android 12 or earlier host with an iPhone joiner
  • Android joining Android

throwaway phase 1 hooks, not a design. android hosts a wi-fi direct group
with given credentials (or a localonlyhotspot) on an adb broadcast, and can
stop its lan carrier so a pair on one network meets only over ble. ios joins
with nehotspotconfiguration from a config file in its container and dials the
host's existing peer-stream listener directly. no udl or js surface.
adr 0038 records the decision from the phase 1 spike: two devices that share
a confirmed session but meet only over bluetooth le bring up a wi-fi direct
network on request, with fresh credentials sealed in the session, and the
stream over it fills the peer-stream slot. the fast link state machine
specifies roles, frames, timers and teardown. threat model r34 records what
the network exposes in range and what the offer trusts.
the literal lives in offline-protocol-sealed with the other pair frames and is
reserved in the engine registry and the control-messages chapter, which also
specifies the request, offer and close bodies and their bounds. until the
handler lands, a fast-link frame is consumed wherever it is found: bare on the
wire, in a 1:1 plaintext, and on all three group plaintext arms, so it is
never shown to anyone as text.
link_versions entry 1 says a peer routes __fast_link__ frames. it is omitted
from the payload when empty, so a key package that does not advertise it is
byte for byte what it was, and a leaf advertises nothing. the engine
advertises it, records it per peer from each key package, persists it with
the other capabilities and restores it at startup. the key package vectors
gain a case, and from_advertised now takes the payload rather than one
argument per list.
crate::fast_link is the state machine of the fast link state machine
document, pure and unit-tested for both ends of a pair: roles, credentials
drawn fresh per link, offer validation, the lower-address rule when both
host, timers, idle teardown, and one close per end. the engine glue gates a
request on capability, a confirmed session and a live direct link, seals
every frame with the strict encryptor and sends it once with no ack or
outbox, routes a decrypted frame from the session, wakes the platform through
the peer-stream callback when a directive waits, and emits fast_link_changed,
which never carries a credential.
request_fast_link and close_fast_link for the application, and four calls
for the peer-stream driver: declare its roles, drain directives on the
callback it already drains bodies on, report its network up, and report an
end. the directive record redacts its passphrase in debug. a stream's proof,
loss, the layer going down and inbound bodies feed the engine's fast link.
every binding, the c dispatcher and the python local api table are
regenerated together, and the local api chapter classifies the new calls.
…m slot

a 1 mib file over a fast link took 8.0 to 8.7 s with four 32 kib chunks in
flight: about 128 kib per acknowledgement round, so the transfer waited on
receipts rather than on the link. the peer-stream slot now keeps sixteen in
flight, 512 kib, well inside the 4 mib a platform manager queues per stream.
every other slot keeps its window.
…o apps

the android manager declares both roles on android 10 and later and drains
the engine's directives on the transport callback. it hosts a wi-fi direct
group with the engine's credentials and reports the owner's address and its
listener's port once the group exists; it joins one by name and passphrase
and dials the offered address and port claiming the host. while hosting, an
inbound stream on the group must prove the invitee, and a group whose client
has left ends its stream at once instead of waiting out keepalive. the
phase 1 spike hooks are gone.

requestFastLink and closeFastLink reach apps on react native and flutter on
both platforms, through the generated bridges, the swift host bridge and the
error manifest. the registration guard learns the callback's second post.
the ios manager declares it can join and not host, and drains the engine's
directives on the transport callback, off the core's mutex. a join applies a
joinonce hotspot configuration, reports a declined prompt as declined, and
dials the offered address and port bound to wi-fi with the host as its claim,
again every two seconds until the stream proves the host or the offer runs
out. backgrounding leaves the network and tells the engine at once, because
ios drops it 15 s later anyway and the host would otherwise wait on
keepalive. the phase 1 spike is gone.
on two phones the example app's presence update every 15 s kept the link
from ever going idle, which kept the iphone off its own wi-fi for as long as
the app ran. only a body of at least 16 kib, half a media chunk on the slot,
now moves the idle clock; a transfer in flight still holds it as before.
…ones

two bugs found on the phones with an iphone-initiated link. the engine sends
a direct frame down the peer stream when it holds one, so a close went down
the stream it was ending and reached the iphone 22 s late, and a request went
down a lan stream the iphone had just left and reached the android 63 s
late. fast-link frames now go over bluetooth le whenever the peer is linked
there. and that late request was hosted, and its offer prompted the iphone's
user to join a network the android had already removed: a device now
remembers the links it ended for ten minutes, drops a late request for one,
and answers a late offer with close expired so the host takes it down.
a link that ended while its platform was paused left its host or join
directive in the queue, and the platform ran it on resume: android brought up
a group for a dead link, and an iphone would prompt for a network already
gone. the machine now counts the platform as holding a link only once it
drains the link's directive, withdraws an untaken one when the link ends,
and skips a host or join whose time ran out.
WifiP2pConfig.Builder throws for a network name that does not start
DIRECT- and two characters, and the engine accepts any name an iphone could
join. an offer with such a name, from any session peer or another
implementation of the spec, threw on the transport looper and killed an
android joiner, again on every offer. the builder is now guarded and the
offer answered invalid, and each directive runs inside a catch so a framework
exception (a revoked permission, say) ends the link as failed instead.
android skipped its fast-link directives while paused, close included, so a
link that ended with the app in the background left its wi-fi direct group
on the air, and blocking every later link, until the app came back. the
directives are now drained whatever the pause; while paused a close still
runs and a new host or join is refused as background, on ios too, where a
join would have prompted a user who is not looking.
…at once

an offer needs no request, so any session peer could put the ios join prompt
in front of a user who never asked, and again the moment it was declined.
after the user declines a peer's network, that peer's offers are answered
declined for ten minutes and never shown; the user's own request to it ends
the pause. threat model r34 records what is left: one prompt per ten minutes
per session.
a host's close can reach the joiner before the late offer it ends, and a
close for a link the joiner did not hold was dropped without trace, so the
offer then prompted. its link id is now remembered like an ended link's, and
the offer is refused as late when it lands.
formation checked only inGroup, which turns true when the group broadcast
lands, seconds after a fast link's createGroup or connect: in that window it
could issue its own join or create and break the one-group rule of adr 0038.
it now waits while a fast link is hosted or joined.
blocking removed the peer's capability but left its link standing: the
android group stayed up for the blocked peer, an iphone joiner stayed off its
own wi-fi, and the blocked peer's own bodies kept the link from going idle.
block_user now ends the link, telling this device's platform to take the
network down and sending nothing to the blocked peer.
a new offer from the same peer replaced a link being joined. on ios the
replaced join's completion then never reported the user's decline, so a peer
that re-offered while each prompt was on screen never started the ten-minute
decline pause that r34 relies on. the second offer is now answered busy and
the first stands; an honest host's new network follows its own close. r34
also records that an android joiner joins with no prompt at all.
…s group is gone

when two android devices host for each other the higher address closes its
own link and joins the other's, and the engine hands its platform the close
and the join in one drain. removeGroup is asynchronous, so the join found the
device still in its group and failed, and both links ended. the join now
waits for the group-gone broadcast, within the offer's lifetime, then runs.
not exercised on hardware: it needs two android phones.
a peer could close its link while the ios prompt was on screen: the user's
cancel then landed on a link the engine no longer held and was dropped, so
the decline pause never began and the next offer prompted again. the engine
remembers which peer each ended join belonged to and records a decline
reported after the end against it, and ios reports the refusal even when the
link is already gone.
…'s host

the dial went to the address the offer named, checked only to be private or
link-local. an android joiner stays on its own wi-fi while in a p2p group, so
an offer naming a host on the user's home network sent the dial, and a
preamble, there instead of over the group. the dial now always goes to the
owner's own address as the group reports it, on the offer's port.
…closed

a close that landed while createGroup was still negotiating sent a
removeGroup the framework can refuse as busy, and the group then came up with
nothing tracking it, blocking every later link and group formation until the
transport stopped. the name of a group closed before it came up is now
remembered, and the group is removed when it appears.
any session peer could make an android host bring up a group by asking, and
by asking again each time the offer expired keep a group on the air and the
device's own formation locked out indefinitely. after two links in a row
hosted for a peer's requests expire with no stream from it, the host answers
that peer's requests busy for ten minutes; a used link resets the count, and
the host's own request to the peer ends the pause. r34 records what is left.

also, an offer that answers this device's request under another id now
leaves the request's id remembered as ended, so a host acting on the request
late cannot prompt the user for a second network.
the unreleased changelog gains the fast link under added and the 16-chunk
peer-stream window under changed, and the mobile permissions guide says what
an integrator needs: the hotspot configuration entitlement and local-network
keys on ios, the wi-fi direct grants and android 10 on android, and what the
user sees.
the fast_link prefix comment said a leaf with a wi-fi radio can host or join
a link, while the capability chapter and the leaf's key package say a leaf
advertises nothing and is never offered one. the comment now agrees.
the c# sdk's generated local api lacked the six fast-link calls, and the two
react native adapters had requestFastLink and closeFastLink placed by hand
where their generators sort them otherwise, so gen_csharp_local_api.py and
check-binding-generators.sh failed their --check. both are regenerated; the
c# suite was not run here (no dotnet).
…ost backoff

the host counted only links that expired toward its request backoff, so a
peer could close each link with any other reason just before it expired and
ask again, holding the android's one group on the air for as long as it
liked. an unused link the peer ended now counts too, whatever its reason;
ends this device caused do not.
any outbound transfer to the peer held the link open, but a transfer's
carrier is fixed when it starts, so one begun over bluetooth before the link
came up never moved to it, and the iphone stayed off its own wi-fi while the
link carried nothing. only a transfer pinned to the peer-stream slot holds
the link now, and the request docs say to send after the link is up.
…y, not its name

NEHotspotNetwork.fetchCurrent names no joinOnce network without location
permission, so on an iphone 16 every join was given up failed five seconds
after the phone was on the group. the host's offered address is the group
owner, the gateway of the wi-fi path, so the dial now waits for that. the
access wi-fi information entitlement and the ios 14 floor are no longer
needed.
…es it

android reports the device out of any group while createGroup is still
forming one, which cleared the name written before it. a host killed while
hosting left its group on the air with nothing on disk, and the next start
adopted it as an ordinary group. device-checked: the group is now removed
on restart.
the gateway check had no bound: a join that apply reported done while the
phone stayed on its own wi-fi waited out its two-minute offer with nothing
said, and the host's group refused every other link meanwhile. after ten
looks, twenty seconds, it now ends failed with a diagnostic.
… forms

the out-of-group broadcast that arrives during createGroup cleared the
name before the group was first seen, so a host killed in that window still
left its group adopted on restart. the broadcast now leaves the name alone
while the hosted group is unseen, and a failed createGroup clears it.
…le is full

returning ended the redial chain, so a join that reached the group with
the table full sat out its two-minute offer with the host's group on the
air. the deadline still bounds the retries.
…ateway

the gateway check could not tell the offered group from the user's own
network when the offer named the home router: a join that silently did not
happen was dialled there on every redial until the offer expired. before
the prompt the host must not already be the wi-fi gateway, looked at up to
four times so a phone still leaving a previous group is not refused.
device-checked: a join and an immediate re-link both reach the prompt.
… the peer first

two phones back on one home network met over it while an offer was
pending; the engine took that stream for the link's own and marked the
link up, the iphone never dialled the group its user had just joined, and
leaving the home network for it lost both. a platform now ends the link
superseded before announcing a stream that is not the link's own, and
answers a directive for a peer a stream already reaches the same way. the
end never counts against the peer and fails no transfer on the slot.
…reached peer gets no link

an android below 13 advertises on its group's interface, so an iphone's
general bonjour dial could prove the host over the group before the link's
own dial; taken for another stream, it superseded the link and tore down
the group it ran on. on ios a stream whose path's gateway is the offered
host, once joined, is now adopted as the link's. and the engine answers a
request or offer from a peer another stream already reaches superseded
itself, with no link: the peer's own superseded could overtake this
device's report and count against the peer.
…d before dhcp stays the link's

when both phones held a pending link and the peer's superseded close
overtook this device's own report, it counted against the peer; with
another stream reaching the peer it is now this device's own end. a peer's
superseded for a link up here is any close, and releases its transfers. a
join the platform has not taken gives way in the engine when a stream
proves the peer. on ios, once joined, only a stream whose path has a
gateway that is not the host supersedes the link: the bonjour stream over
the group proves over a link-local address before dhcp, with no gateway,
and was ended with the group it ran on. android lets a parked join give
way too.
…nd the superseded guard says what it covers

a stream that proves the peer while the host's group is still coming up
cannot be the link's own, so the link now ends superseded before any offer
is sent. the guard for a peer's superseded covers a stream this device has
already proved but its platform did not recognise; one that arrives before
this device proves the stream at all is still counted, and the docs, the
comment and the test names now say so. the test also checks a peer's
superseded for an up link releases its transfers and is counted.
@mizanxali
mizanxali marked this pull request as ready for review November 17, 2026 13:02
…gate the named group on api 29 for lint

main's typescript event parser keeps a list of every event tag, and its
guard refused the branch's new one. android lint refused the named-group
createGroup call below api 29; the fast link was already off there at
runtime, and the check now sits where the call is made.
@mizanxali
mizanxali requested a review from bahdotsh November 17, 2026 13:20

@bahdotsh bahdotsh left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@bahdotsh
bahdotsh merged commit 043cece into main Nov 17, 2026
45 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 17, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants