From 4df7c132315aeedbc82414c5087c0848932598c5 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 14:33:03 +0100 Subject: [PATCH 1/4] docs(adr): propose 0079, an Android worker may enrol phones reached over the network (#1589) --- ...y-enrol-phones-reached-over-the-network.md | 128 ++++++++++++++++++ docs/internal/adr/README.md | 1 + 2 files changed, 129 insertions(+) create mode 100644 docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md diff --git a/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md b/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md new file mode 100644 index 000000000..c82c5c14c --- /dev/null +++ b/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md @@ -0,0 +1,128 @@ +# 0079. An Android worker may enrol phones reached over the network + +- **Status:** Proposed +- **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 state `device` counts as a +phone the driver may enrol, list as present and list for auto-enrolment. +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 lease, reclaim or uninstall + reaches another phone at the same address. +- A phone whose hardware serial is already enrolled, as a USB serial or as + another record's hardware serial, is refused. One phone keeps one record + (ADR 0022 §6 step 3). +- 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 + +On every watcher tick, the worker runs `adb connect ` for each +enrolled `host:port` phone that the default server does not list, behind +the protocol check and within a time limit. 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 of a network phone costs one more `getprop`. +- 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. +- 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 2694fb086..d7c187606 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -111,3 +111,4 @@ the status is stale. | [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 | | [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 | +| [0079](0079-an-android-worker-may-enrol-phones-reached-over-the-network.md) | An Android worker may enrol phones reached over the network | Proposed | From a3fb18f1f330e58ea7287546f24f58eb079f6145 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 14:49:42 +0100 Subject: [PATCH 2/4] docs(adr): 0079 checks the serial before a reclaim, reconnects inside every presence read (#1589) --- ...y-enrol-phones-reached-over-the-network.md | 32 +++++++++++++------ 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md b/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md index c82c5c14c..e7541bb5d 100644 --- a/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md +++ b/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md @@ -64,11 +64,20 @@ flowchart LR ``` - Every presence read of a network phone reads the hardware serial again. - A different one reads not present, so no lease, reclaim or uninstall - reaches another phone at the same address. + 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. One phone keeps one record - (ADR 0022 §6 step 3). + 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. @@ -79,9 +88,11 @@ need a rule for which transport to use. ### 3. The worker reconnects the phones it enrolled -On every watcher tick, the worker runs `adb connect ` for each -enrolled `host:port` phone that the default server does not list, behind -the protocol check and within a time limit. It connects only 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. @@ -121,8 +132,11 @@ Safety rules 1, 7 and 8 gain one exception each, under this key only: - 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 of a network phone costs one more `getprop`. +- 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. + 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`. From af969abdff53cb91e6ac9b96feccf7fa9d8880ee Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 14:51:59 +0100 Subject: [PATCH 3/4] docs(adr): accept 0079, not yet implemented (#1589) --- ...roid-worker-may-enrol-phones-reached-over-the-network.md | 2 +- docs/internal/adr/README.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md b/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md index e7541bb5d..6e1db9d98 100644 --- a/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md +++ b/docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md @@ -1,6 +1,6 @@ # 0079. An Android worker may enrol phones reached over the network -- **Status:** Proposed +- **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) diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index d7c187606..de9d80e88 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 0079 | | [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 | @@ -107,8 +107,8 @@ 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 0079 | | [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 | | [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 | -| [0079](0079-an-android-worker-may-enrol-phones-reached-over-the-network.md) | An Android worker may enrol phones reached over the network | Proposed | +| [0079](0079-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 | From f2e4ffa0ec96b885f3ad4c4f7d8da190bfc7c8c1 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 21:08:55 +0100 Subject: [PATCH 4/4] docs(adr): renumber the network-phones ADR to 0080 and list its phones in any state (#1589) --- ...id-worker-may-enrol-phones-reached-over-the-network.md} | 7 ++++--- docs/internal/adr/README.md | 6 +++--- 2 files changed, 7 insertions(+), 6 deletions(-) rename docs/internal/adr/{0079-an-android-worker-may-enrol-phones-reached-over-the-network.md => 0080-an-android-worker-may-enrol-phones-reached-over-the-network.md} (96%) diff --git a/docs/internal/adr/0079-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 similarity index 96% rename from docs/internal/adr/0079-an-android-worker-may-enrol-phones-reached-over-the-network.md rename to docs/internal/adr/0080-an-android-worker-may-enrol-phones-reached-over-the-network.md index 6e1db9d98..ea0665443 100644 --- a/docs/internal/adr/0079-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 @@ -1,4 +1,4 @@ -# 0079. An Android worker may enrol phones reached over the network +# 0080. An Android worker may enrol phones reached over the network - **Status:** Accepted — not yet implemented - **Date:** 2026-11-16 @@ -40,8 +40,9 @@ first passes the default server's protocol check (ADR 0022 §5). 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 state `device` counts as a -phone the driver may enrol, list as present and list for auto-enrolment. +`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. diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index f7bf015bb..a60858103 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; §6 and §7 narrowed by 0079 | +| [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,10 @@ 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; §2 and §5 narrowed by 0079 | +| [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 | | [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 | -| [0079](0079-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 | | [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 |