Repository navigation
docs(adr): propose 0079, an Android worker may enrol phones reached over the network (#1589) #1594
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
4df7c13
a3fb18f
af969ab
1472305
f2e4ffa
767c5a6
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,143 @@ | ||
| # 0080. An Android worker may enrol phones reached over the network | ||
|
|
||
| - **Status:** Accepted — not yet implemented | ||
| - **Date:** 2026-11-16 | ||
| - **Issue:** [#1589](https://github.com/callstackincubator/simlock/issues/1589) (request [#1250](https://github.com/callstackincubator/simlock/issues/1250)) | ||
| - **Narrows:** [ADR 0022](0022-a-physical-device-is-a-second-device-type-the-core-knows.md) | ||
| §6 ("inspect the ID over USB only … A device reachable only over the | ||
| network is refused") and §7 ("present when its handler lists it on | ||
| USB"); [ADR 0073](0073-a-worker-may-enrol-the-phones-plugged-into-it.md) | ||
| §2 ("A phone reached only over the network is not listed") and §5. | ||
| - **Depends on:** ADR 0022, 0073. | ||
|
|
||
| ## Context | ||
|
|
||
| A phone farm wired by Ethernet reaches its phones with `adb connect | ||
| <ip>:5555`. Their USB ports hold the network adapters, so no phone has a | ||
| USB path to a worker. Android 11 and later can also be reached by | ||
| wireless debugging: once paired, adb lists the phone under an mDNS name, | ||
| for example `adb-R58Y61A60HN-r7wg2G._adb-tls-connect._tcp`, and connects | ||
| to it again by itself. | ||
|
|
||
| ADR 0022 refuses any phone reached only over the network. Its reasons hold | ||
| for USB: the default adb server owns the transport, and the USB serial is | ||
| the phone's own identity. Over the network, neither holds: | ||
|
|
||
| - the name adb lists is an **address**. DHCP can give `192.168.1.5` to | ||
| another phone, which would then be leased and cleaned up under the first | ||
| phone's record; | ||
| - one phone on both USB and the network is listed twice, under two names; | ||
| - a restart of the default adb server forgets every `host:port` | ||
| transport, and nobody connects them again. | ||
|
|
||
| What a worker already does: the physical-device watcher reads every | ||
| enrolled phone every `health.probeIntervalMs`, and every physical command | ||
| first passes the default server's protocol check (ADR 0022 §5). | ||
|
|
||
| ## Decision | ||
|
|
||
| ### 1. A worker key opts the Android driver in | ||
|
|
||
| The Android driver gains a worker key (named in the feature's design). | ||
| Off, the default, nothing changes: a network-only phone is refused | ||
| `network-only`. On, a network transport, in any state, counts as a | ||
| phone the driver may enrol and list for auto-enrolment; it is present | ||
| only in state `device`. | ||
| An emulator is never one, whatever transport it is on. USB phones are | ||
| unchanged. | ||
|
|
||
| The key is the operator's consent for the network the worker's adb server | ||
| reaches, the way `devices.autoEnroll` is consent for its USB ports. | ||
|
|
||
| ### 2. The ID is the address, and the hardware serial proves the phone | ||
|
|
||
| A network phone's ID is the name adb lists it under: what `adb -s` takes, | ||
| and what `ANDROID_SERIAL` carries in a lease. The phone's hardware serial | ||
| (`ro.serialno`) is read at enrolment and kept on its record. | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| R[presence read] --> L{address listed, state device?} | ||
| L -- no --> N[not present] | ||
| L -- yes --> S{ro.serialno equals the recorded one?} | ||
| S -- no --> N | ||
| S -- yes --> P[present] | ||
| ``` | ||
|
|
||
| - Every presence read of a network phone reads the hardware serial again. | ||
| A different one reads not present, so no grant reaches another phone at | ||
| the same address. | ||
| - A reclaim reads it first too, because a lease can end before the watcher | ||
| sees the address change hands. A different one fails the reclaim before | ||
| any uninstall, and the phone goes absent until it is back. | ||
| - `device.exec`, the screen and tunnels on a leased phone do not read it | ||
| before each command. Between the address changing hands and the | ||
| watcher ending the lease `device-lost`, those commands can reach the | ||
| other phone. They delete nothing Simlock cannot put back, and a read | ||
| before each would double every command's cost. | ||
|
Comment on lines
+73
to
+77
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Declare the command window as a safety exception, or check the serial before commands. Section 2 accepts that Choose one of two corrections:
|
||
| - A phone whose hardware serial is already enrolled, as a USB serial or as | ||
| another record's hardware serial, is refused, whatever the key says. One | ||
| phone keeps one record (ADR 0022 §6 step 3); two would uninstall each | ||
| other's apps. | ||
| - A phone that moves to a new address reads absent. The operator removes | ||
| it and adds it at its new address. | ||
|
|
||
| Rejected: the hardware serial as the ID, with the address stored apart. | ||
| One record per phone whatever its address, but the core would map an ID | ||
| to an address for every lease and command, and a phone listed twice would | ||
| need a rule for which transport to use. | ||
|
|
||
| ### 3. The worker reconnects the phones it enrolled | ||
|
|
||
| Inside every presence read (the watcher's, a grant's, a reclaim's or a | ||
| quarantine retry's), the driver runs `adb connect <host:port>` for each | ||
| enrolled `host:port` phone that the default server does not list, all at | ||
| once, behind the protocol check and within a time limit, then reads the | ||
| list again. It connects only enrolled | ||
| addresses. It never runs `disconnect`, `pair` or `tcpip`, and it still | ||
| never starts or stops the server on purpose. A wireless-debugging phone | ||
| listed under an mDNS name is left to adb, which connects it again itself. | ||
|
|
||
| `adb connect` exits 0 when it fails, so the worker reads the outcome from | ||
| the next listing, never from the exit code. | ||
|
|
||
| Pairing a wireless-debugging phone (`adb pair` and its code) stays the | ||
| operator's job. Simlock never handles a pairing code. | ||
|
|
||
| Rejected: the operator keeps every transport up. Every farm would keep a | ||
| script, and one restart of the default server would leave the whole farm | ||
| absent. | ||
|
|
||
| ### 4. Auto-enrolment covers network phones under both keys | ||
|
|
||
| With this key and `devices.autoEnroll` both on, the host-level list of | ||
| ADR 0073 §2 also lists the network phones the default server lists. The | ||
| operator runs `adb connect` once for each phone; the worker enrols it and | ||
| keeps it connected from then on. | ||
|
|
||
| ### 5. Safety | ||
|
|
||
| Safety rules 1, 7 and 8 gain one exception each, under this key only: | ||
|
|
||
| - the host-level list includes network transports; | ||
| - `device add`'s read-only inspection, and the hardware-serial read of a | ||
| presence check, may reach a phone that answers at an enrolled address | ||
| but is not the enrolled phone. Both are reads; nothing destructive runs | ||
| until the serial matches; | ||
| - `adb connect` runs for an enrolled address. | ||
|
|
||
| ## Consequences | ||
|
|
||
| - A developer's own Wi-Fi phone connected to a worker with both keys on is | ||
| enrolled and leased. The docs say so next to the key. | ||
| - Anyone on the network who can reach a phone's adb port and has an | ||
| authorized key can drive it outside Simlock. adb over TCP is as open as | ||
| the network it runs on; this is the operator's to secure. | ||
| - Every presence read and every reclaim of a network phone costs one more | ||
| `getprop`. A presence read that has to reconnect waits up to the | ||
| reconnect's time limit, which also delays grants of the worker's other | ||
| Android phones. | ||
| - The physical record gains one optional field in the core's schema. The | ||
| contract does not carry it, and the driver's new key is no contract | ||
| shape change. The new refusal reason is one, so the protocol is bumped. | ||
| - A phone that changes address needs a `device remove` and a `device add`. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reclaim leaves a window where its uninstalls can reach a replacement phone.
The reclaim reads
ro.serialnoonce, before its uninstalls. If phone A disconnects after that read and phone B takes its address, the lateradb -s <address>uninstalls can reach B. The ADR accepts this window only for lease commands, and its reason (the commands delete nothing Simlock cannot restore) does not cover uninstalls. The ADR should either bind each reclaim uninstall to the verified phone, for example by reading the serial again before each destructive command, or state explicitly which identity check the reclaim relies on and why the window is acceptable.