diff --git a/docs/internal/adr/0080-an-android-worker-may-enrol-phones-reached-over-the-network.md b/docs/internal/adr/0080-an-android-worker-may-enrol-phones-reached-over-the-network.md new file mode 100644 index 000000000..ea0665443 --- /dev/null +++ b/docs/internal/adr/0080-an-android-worker-may-enrol-phones-reached-over-the-network.md @@ -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 +: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. +- 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 ` 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`. diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index b413bc3e1..ac71ce2c8 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -60,7 +60,7 @@ the status is stale. | [0019](0019-startup-ends-every-lease-whose-device-is-not-running.md) | Startup ends every lease whose device is not running | Accepted; §1–2 narrowed by 0022 for physical devices; §4 narrowed by 0036 (a replay reads the current device) | | [0020](0020-a-requester-may-choose-its-lease-id.md) | A requester may choose its lease id, and the gateway passes it through bare | Accepted; §1 superseded in part by 0074 | | [0021](0021-a-gateway-dispatch-is-a-probe-and-names-its-fleet-request.md) | A gateway dispatch is a probe, and the gateway records every fleet request's outcome | Accepted — partly implemented: §5 (usage figures) is not built | -| [0022](0022-a-physical-device-is-a-second-device-type-the-core-knows.md) | A physical device is a second device type the core knows | Accepted; amends 0001 §3 and §5, 0015 §3 and 0019 §1–2 for physical devices; §3, §5 and §6 narrowed by 0073 | +| [0022](0022-a-physical-device-is-a-second-device-type-the-core-knows.md) | A physical device is a second device type the core knows | Accepted; amends 0001 §3 and §5, 0015 §3 and 0019 §1–2 for physical devices; §3, §5 and §6 narrowed by 0073; §6 and §7 narrowed by 0080 | | [0023](0023-agent-device-is-served-by-an-optional-edge-module.md) | agent-device is served by an optional edge module, and the simlock lease is the only clock | Accepted; §1 narrowed by 0026 for gateway mode; §3 narrowed by 0030 (no reap while turned off); §3–4 superseded in part by 0043; §1, §3–4 narrowed by 0046; §2 and §4 narrowed by 0070; §3 superseded in part by 0071 | | [0024](0024-leasing-calls-lease-end-participants-before-reclaim.md) | Leasing calls lease-end participants before it reclaims a device | Accepted | | [0025](0025-simlock-ships-android-profiles-and-a-model-pairs-only-with-images-that-fit.md) | Simlock ships Android device profiles, and a model pairs only with images that fit it | Accepted; §4 narrowed by 0078 | @@ -107,10 +107,11 @@ the status is stale. | [0069](0069-a-learned-kind-keeps-one-ready-copy-while-its-copies-are-leased.md) | A learned kind keeps one ready copy while its copies are leased | Accepted; narrows 0038 §2 and §3 | | [0070](0070-test-runners-drive-a-lease-through-the-agent-device-front.md) | Test runners drive a lease through the agent-device front: boot is answered, a close may keep the lease, and each lease is its own tenant | Accepted; narrows 0023 §2 and §4; §2 narrowed by 0071 | | [0071](0071-a-restart-re-allocates-a-live-agent-device-lease.md) | A restart re-allocates a live agent-device lease on its device | Accepted; supersedes 0023 §3 in part; narrows 0070 §2 | -| [0073](0073-a-worker-may-enrol-the-phones-plugged-into-it.md) | A worker may enrol the phones plugged into it | Accepted; narrows 0022 §3, §5 and §6 | +| [0073](0073-a-worker-may-enrol-the-phones-plugged-into-it.md) | A worker may enrol the phones plugged into it | Accepted; narrows 0022 §3, §5 and §6; §2 and §5 narrowed by 0080 | | [0074](0074-an-admission-command-ranks-or-refuses-a-gateway-request-and-an-ended-chosen-lease-id-is-remembered.md) | An admission command ranks or refuses a gateway request, and an ended chosen lease id is remembered | Accepted; narrows 0005 items 10 and 11, decision 5 and requirements 14 and 30; supersedes 0020 §1 in part | | [0075](0075-a-foldable-simulator-streams-the-panel-in-use-and-a-stream-may-change-size.md) | A foldable simulator streams the panel in use, and a stream may change size while it runs | Accepted; narrows 0031's Consequences and 0052 §4 | | [0076](0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md) | An iOS clone names only its own folders before its first boot | Accepted; narrows 0061 §1, §2 and §4 | | [0077](0077-the-repository-is-a-workspace-and-its-packages-release-together-under-one-version.md) | The repository is a workspace, and its packages release together under one version | Accepted | | [0078](0078-an-android-worker-tries-its-default-image-tag-first-and-falls-back-to-none.md) | An Android worker tries its default image tag first, and a lease falls back to none | Accepted | | [0079](0079-one-capture-per-device-is-shared-by-every-viewer-and-every-capture-sends-a-key-frame-every-5-s.md) | One capture per device is shared by every viewer, and every capture sends a key frame at least every 5 s | Accepted; narrows 0045 §5 | +| [0080](0080-an-android-worker-may-enrol-phones-reached-over-the-network.md) | An Android worker may enrol phones reached over the network | Accepted — not yet implemented; narrows 0022 §6 and §7, and 0073 §2 and §5 |