Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
d38b302
test: device add refuses a phone whose hardware serial another live r…
V3RON Nov 16, 2026
2d5dc31
feat(core): device add refuses a phone whose hardware serial another …
V3RON Nov 16, 2026
e9ebb64
test: a physical record's hardware serial survives a reload (#1604)
V3RON Nov 16, 2026
24d0bb1
feat(registry): a physical record keeps its hardware serial across a …
V3RON Nov 16, 2026
5832889
test: a v6 state.db migrates and then stores a hardware serial (#1604)
V3RON Nov 16, 2026
f00c65d
test: every presence read passes each record's driverDeviceId and har…
V3RON Nov 16, 2026
3c1ebec
feat(core): every presence read passes each record's driverDeviceId a…
V3RON Nov 16, 2026
47d9a3a
test: presence-read helpers read the IDs of the entries a driver was …
V3RON Nov 16, 2026
6db7163
feat(core): a physical reclaim hands the driver the record's hardware…
V3RON Nov 16, 2026
195dafa
test: device add refuses a phone another live record's hardware seria…
V3RON Nov 16, 2026
5f4d960
feat(core): device add refuses a phone another live record's hardware…
V3RON Nov 16, 2026
5b82860
test: re-enrol takes the new read's hardware serial and a late clash …
V3RON Nov 16, 2026
f0a8393
feat(core): re-enrol takes the new hardware serial and checks it at i…
V3RON Nov 16, 2026
ab3469c
test: the worker auto-enrols a listed network ID and refuses one whos…
V3RON Nov 16, 2026
aa3a036
docs(website): the error and reasons tables list enrolled-under-other…
V3RON Nov 16, 2026
42df6c5
Merge remote-tracking branch 'origin/feature/1589-adr' into HEAD
V3RON Nov 16, 2026
f951fed
test: re-enrolling a phone with its own hardware serial is not a clas…
V3RON Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions e2e/fake-driver/fake-driver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ import {
type PassthroughCommand,
type PassthroughContext,
type PhysicalInspection,
type EnrolledPhysical,
type PresentPhysical,
uninstallPlan,
PassthroughRefusedError,
Expand Down Expand Up @@ -604,9 +605,11 @@ export class OutOfProcessFakeDriver implements Driver {
};
}

async listPresentPhysical(enrolledIds: readonly string[]): Promise<readonly PresentPhysical[]> {
const script = await this.#beforeCall("listPresentPhysical", [enrolledIds]);
return enrolledIds.map((driverDeviceId) => {
async listPresentPhysical(
enrolled: readonly EnrolledPhysical[],
): Promise<readonly PresentPhysical[]> {
const script = await this.#beforeCall("listPresentPhysical", [enrolled]);
return enrolled.map(({ driverDeviceId }) => {
const scripted = script.physicalDevices?.find((candidate) =>
candidate.ids.includes(driverDeviceId),
);
Expand Down Expand Up @@ -646,6 +649,7 @@ export class OutOfProcessFakeDriver implements Driver {
enrollable: true,
model: device.model ?? "Fake Phone",
osVersion: device.osVersion ?? "1.0",
...(device.hardwareSerial === undefined ? {} : { hardwareSerial: device.hardwareSerial }),
};
}

Expand Down
1 change: 1 addition & 0 deletions e2e/fake-driver/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ export interface ScriptedPhysicalDevice {
readonly class?: "phone" | "tablet";
readonly apps?: readonly string[];
readonly installedApps?: readonly string[];
readonly hardwareSerial?: string;
readonly present?: boolean;
readonly absentReason?: "locked" | "untrusted" | "not-present";
readonly refusal?: { readonly reason: FakeDriverRefusalReason; readonly message: string };
Expand Down
24 changes: 24 additions & 0 deletions e2e/physical-enrollment-auto-enroll.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,30 @@ describe("devices.autoEnroll", () => {
).toEqual(["operator"]);
});

it("enrols a listed network ID with no record as auto, and refuses one whose hardware serial is already enrolled as enrolled-under-other-id, logged once, with no event", async () => {
const network = (address: string): ScriptedPhysicalDevice => ({
...PIXEL,
hardwareSerial: "R58M123ABC",
ids: [address],
});
const env = await autoDaemon({ android: { physicalDevices: [network("192.168.1.5:5555")] } });
await waitFor(async () => (await named(env, "device.enrolled")).length === 1, {
label: "the network phone is enrolled",
});

await plug(env, "android", [network("192.168.1.5:5555"), network("192.168.1.9:5555")]);
await waitFor(async () => (await autoEnrollLog(env)).length === 1, { label: "the refusal" });
await observeFor(700, async () => {
expect(await autoEnrollLog(env), "several runs at one reason write one line").toEqual([
"auto-enroll: android 192.168.1.9:5555 not enrolled: this phone (hardware serial R58M123ABC) is enrolled as 192.168.1.5:5555; remove that record first",
]);
});

expect((await named(env, "device.enrolled")).map((entry) => entry.payload)).toEqual([
expect.objectContaining({ driverDeviceId: "192.168.1.5:5555", initiator: "auto" }),
]);
});

it("forgets which phones are held out when the daemon restarts, so a removed phone still plugged in is enrolled on the first run", async () => {
const env = await autoDaemon({ ios: { physicalDevices: [IPHONE] } });
await waitFor(async () => (await named(env, "device.enrolled")).length === 1, {
Expand Down
27 changes: 27 additions & 0 deletions e2e/physical-enrollment.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,33 @@ describe("simlock device add", () => {
});
});

it("of a phone whose hardware serial another record holds answers enrolled-under-other-id with the message and the canonicalId that record holds, over the CLI and HTTP, and writes no second record", async () => {
const network = "192.168.1.5:5555";
const daemon = await httpDaemon({
android: {
physicalDevices: [PIXEL, { ...PIXEL, hardwareSerial: PIXEL.ids[0], ids: [network] }],
},
});
const enrolled = await add(daemon.env, "android", PIXEL.ids[0] as string);
const message = `this phone (hardware serial ${PIXEL.ids[0]}) is enrolled as ${PIXEL.ids[0]}; remove that record first`;

const result = await daemon.env.cli(["device", "add", "--platform", "android", network]);
const http = await postDevice(daemon, { id: network, platform: "android" });

expect(result.code, result.stderr).toBe(12);
expect(result.error).toEqual({ code: "DEVICE_NOT_ENROLLABLE", message });
expect(http.status).toBe(422);
expect(http.body.error).toEqual({
canonicalId: PIXEL.ids[0],
code: "DEVICE_NOT_ENROLLABLE",
id: network,
message,
platform: "android",
reason: "enrolled-under-other-id",
});
expect((await rows(daemon.env)).map((row) => row.id)).toEqual([enrolled.id]);
});

it("without --platform exits 2 with USAGE and the driver log has no inspectPhysical call", async () => {
const env = await startDaemon({ ios: { physicalDevices: [IPHONE] } });
await env.driverLog.clear();
Expand Down
1 change: 1 addition & 0 deletions src/contract/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ const DEVICE_NOT_ENROLLABLE_REASONS = [
"unreadable",
"virtual-device",
"enrolled-on-other-platform",
"enrolled-under-other-id",
] as const;

export type DeviceNotEnrollableReason = (typeof DEVICE_NOT_ENROLLABLE_REASONS)[number];
Expand Down
2 changes: 1 addition & 1 deletion src/contract/protocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ export interface ProtocolRange {
const protocolRangeSchema = z.object({ min: z.number().int(), max: z.number().int() });

/** Widen only once a second version is kept alive side by side with the first; a bump that leaves no shim behind moves both ends. */
export const PROTOCOL_VERSION_RANGE: ProtocolRange = { min: 89, max: 91 };
export const PROTOCOL_VERSION_RANGE: ProtocolRange = { min: 89, max: 92 };

const LEGACY_DAEMON_PROTOCOL_VERSION = 2;

Expand Down
2 changes: 2 additions & 0 deletions src/core/domain.ts
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,8 @@ export interface PhysicalDevice extends DeviceRecordFields {
readonly spec: PhysicalSpec;
readonly state: PhysicalState;
readonly enrolledApps: readonly string[];
/** why: a network phone's `ro.serialno`, kept so every presence read can check the address still reaches that phone (ADR 0080 §2); absent for a USB phone. */
readonly hardwareSerial?: string;
readonly reclaimingSince?: number;
readonly absentReason?: AbsentReason;
readonly mode?: undefined;
Expand Down
9 changes: 8 additions & 1 deletion src/core/driver.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -215,10 +215,17 @@ describe("PhysicalInspection (ADR 0022 §5)", () => {
// @ts-expect-error only the core can know a device is enrolled on the other platform
reason: "enrolled-on-other-platform",
};
const otherId: PhysicalInspection = {
enrollable: false,
message: "enrolled as another ID",
// @ts-expect-error only the core can know a phone is enrolled under another ID
reason: "enrolled-under-other-id",
};
void otherPlatform;
void otherId;
}

it("lets a driver refuse with every reason but enrolled-on-other-platform", () => {
it("lets a driver refuse with every reason but enrolled-on-other-platform and enrolled-under-other-id", () => {
const reasons: Record<DriverRefusalReason, true> = {
"developer-mode-off": true,
locked: true,
Expand Down
19 changes: 17 additions & 2 deletions src/core/driver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,12 +54,20 @@ export type VirtualDriverDevice = DriverDevice & { readonly physical: false };
export type PhysicalDriverDevice = DriverDevice & {
readonly physical: true;
readonly enrolledApps: readonly string[];
/** why: set for a network phone only, so the driver checks it still reaches that phone (ADR 0080 §2). */
readonly hardwareSerial?: string;
};

export function isPhysicalDriverDevice(device: DriverDevice): device is PhysicalDriverDevice {
return (device as Partial<PhysicalDriverDevice>).physical === true;
}

/** why: what a presence read asks about one enrolled phone; the hardware serial lets a driver tell a phone from another one at the same network address (ADR 0080 §2). */
export interface EnrolledPhysical {
readonly driverDeviceId: string;
readonly hardwareSerial?: string;
}

export interface PresentPhysical {
readonly driverDeviceId: string;
readonly present: boolean;
Expand All @@ -77,7 +85,12 @@ export function toDriverDevice(device: DeviceRecord): VirtualDriverDevice | Phys
driverData: device.driverData,
};
return device.physical
? { ...base, enrolledApps: device.enrolledApps, physical: true }
? {
...base,
enrolledApps: device.enrolledApps,
...(device.hardwareSerial === undefined ? {} : { hardwareSerial: device.hardwareSerial }),
physical: true,
}
: { ...base, physical: false };
}

Expand Down Expand Up @@ -228,6 +241,8 @@ export type PhysicalInspection =
readonly osVersion: string;
readonly class: PhysicalClass;
readonly apps: readonly string[];
/** why: a network phone's `ro.serialno`, so one phone keeps one record whatever address it is reached at (ADR 0080 §2); absent for USB phones. */
readonly hardwareSerial?: string;
}
| {
readonly enrollable: false;
Expand Down Expand Up @@ -322,7 +337,7 @@ export interface Driver {
destroy(device: VirtualDriverDevice): Promise<void>;
listManaged(): Promise<DriverReality>;
inspectPhysical(id: string): Promise<PhysicalInspection>;
listPresentPhysical(enrolledIds: readonly string[]): Promise<readonly PresentPhysical[]>;
listPresentPhysical(enrolled: readonly EnrolledPhysical[]): Promise<readonly PresentPhysical[]>;
/** why: a read made beyond enrolled IDs; canonical IDs of the phones on USB in any state, sorted, no duplicates, and a throw (never an empty list) when the platform cannot be read. */
listAttachedPhysical(): Promise<readonly string[]>;
listCatalog(): Promise<DriverCatalogEntry>;
Expand Down
20 changes: 14 additions & 6 deletions src/core/fake-driver.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -174,9 +174,11 @@ describe("FakeDriver", () => {
driver.setPhysicalPresence("A", true);
driver.holdPresenceReads("A");
let answer: readonly unknown[] | undefined;
const read = driver.listPresentPhysical(["B", "A"]).then((entries) => {
answer = entries;
});
const read = driver
.listPresentPhysical([{ driverDeviceId: "B" }, { driverDeviceId: "A" }])
.then((entries) => {
answer = entries;
});

await new Promise((resolve) => setTimeout(resolve, 5));
expect(answer).toBeUndefined();
Expand All @@ -196,7 +198,7 @@ describe("FakeDriver", () => {
driver.releasePresenceReads();

const answer = await Promise.race([
driver.listPresentPhysical(["A"]),
driver.listPresentPhysical([{ driverDeviceId: "A" }]),
new Promise((resolve) => setTimeout(() => resolve("held"), 25)),
]);

Expand All @@ -209,7 +211,13 @@ describe("FakeDriver", () => {
driver.setPhysicalPresence("B", true, { osVersion: "18.5" });
driver.setPhysicalPresence("C", false);

await expect(driver.listPresentPhysical(["A", "B", "C"])).resolves.toEqual([
await expect(
driver.listPresentPhysical([
{ driverDeviceId: "A" },
{ driverDeviceId: "B" },
{ driverDeviceId: "C" },
]),
).resolves.toEqual([
{ driverDeviceId: "A", present: false, reason: "locked" },
{ driverDeviceId: "B", osVersion: "18.5", present: true },
{ driverDeviceId: "C", present: false, reason: "not-present" },
Expand All @@ -221,7 +229,7 @@ describe("FakeDriver", () => {
driver.setPhysicalPresence("A", true, { osVersion: "18.5" });
driver.setPhysicalPresence("A", true);

await expect(driver.listPresentPhysical(["A"])).resolves.toEqual([
await expect(driver.listPresentPhysical([{ driverDeviceId: "A" }])).resolves.toEqual([
{ driverDeviceId: "A", osVersion: "1.0", present: true },
]);
});
Expand Down
13 changes: 9 additions & 4 deletions src/core/fake-driver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ import {
type PhysicalDriverDevice,
type VirtualDriverDevice,
type PhysicalInspection,
type EnrolledPhysical,
type PresentPhysical,
type ReclaimResult,
removeListedComponent,
Expand Down Expand Up @@ -77,6 +78,7 @@ export interface FakePhysicalDevice {
readonly osVersion?: string;
readonly class?: PhysicalClass;
readonly apps?: readonly string[];
readonly hardwareSerial?: string;
readonly refusal?: { readonly reason: DriverRefusalReason; readonly message: string };
}

Expand Down Expand Up @@ -609,14 +611,16 @@ export class FakeDriver implements Driver {
this.#physicalDevices = devices;
}

async listPresentPhysical(enrolledIds: readonly string[]): Promise<readonly PresentPhysical[]> {
await this.#beforeCall("listPresentPhysical", enrolledIds);
if (enrolledIds.some((id) => this.#heldPresenceReads.has(id))) {
async listPresentPhysical(
enrolled: readonly EnrolledPhysical[],
): Promise<readonly PresentPhysical[]> {
await this.#beforeCall("listPresentPhysical", enrolled);
if (enrolled.some(({ driverDeviceId }) => this.#heldPresenceReads.has(driverDeviceId))) {
await new Promise<void>((resolve) => {
this.#pendingPresenceReads.push(resolve);
});
}
return enrolledIds.map((driverDeviceId) => {
return enrolled.map(({ driverDeviceId }) => {
if (this.#presentPhysical.has(driverDeviceId)) {
return {
driverDeviceId,
Expand Down Expand Up @@ -898,6 +902,7 @@ function readPhysical(device: FakePhysicalDevice, id: string): PhysicalInspectio
enrollable: true,
model: device.model ?? "Fake Phone",
osVersion: device.osVersion ?? "1.0",
...(device.hardwareSerial === undefined ? {} : { hardwareSerial: device.hardwareSerial }),
};
}

Expand Down
1 change: 1 addition & 0 deletions src/core/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ export {
type DriverRefusalReason,
type VirtualDriverDevice,
type PhysicalInspection,
type EnrolledPhysical,
type PresentPhysical,
toDriverDevice,
uninstallPlan,
Expand Down
80 changes: 80 additions & 0 deletions src/core/physical-enrollment.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -597,6 +597,86 @@ describe("PhysicalEnrollment", () => {
expect(physicalRecords(harness)).toHaveLength(2);
});

it("refuses a phone whose hardware serial another live record already holds, whatever either one's transport, naming that record, and writes nothing; a deleted holder refuses nothing", async () => {
const usb = { ids: ["R58Y61A60HN"] };
const network = { hardwareSerial: "R58Y61A60HN", ids: ["192.168.1.5:5555"] };
const otherAddress = { hardwareSerial: "R58Y61A60HN", ids: ["192.168.1.9:5555"] };
const cases = [
{ candidate: network, holder: usb, holds: "R58Y61A60HN" },
{ candidate: otherAddress, holder: network, holds: "192.168.1.5:5555" },
{ candidate: usb, holder: network, holds: "192.168.1.5:5555" },
];

for (const { candidate, holder, holds } of cases) {
const control = await build([candidate]);
await control.core.enrollment.add("ios", candidate.ids[0] as string);
expect(live(control)).toHaveLength(1);
const harness = await build([holder, candidate]);
await harness.core.enrollment.add("ios", holder.ids[0] as string);

const refused = harness.core.enrollment.add("ios", candidate.ids[0] as string);

await expect(refused).rejects.toMatchObject({
canonicalId: holds,
message: `this phone (hardware serial R58Y61A60HN) is enrolled as ${holds}; remove that record first`,
name: "DeviceNotEnrollableError",
reason: "enrolled-under-other-id",
});
expect(live(harness).map((device) => device.driverDeviceId)).toEqual([holder.ids[0]]);

await harness.core.enrollment.remove(holder.ids[0] as string);
await harness.core.enrollment.add("ios", candidate.ids[0] as string);
expect(live(harness).map((device) => device.driverDeviceId)).toEqual([candidate.ids[0]]);
}
});

it("re-enrols with the hardware serial the new read carries, and refuses a clash that appears after an inspection, at the first commit or the second, leaving the record as it was", async () => {
const network = "192.168.1.5:5555";
const taking = await build([{ hardwareSerial: "SER-1", ids: [network] }]);
await taking.core.enrollment.add("ios", network);
const same = await taking.core.enrollment.add("ios", network);
expect(same.reenrolled, "same ID, same serial").toBe(true);
taking.driver.setPhysicalDevices([{ hardwareSerial: "SER-2", ids: [network] }]);
const again = await taking.core.enrollment.add("ios", network);
expect(again.reenrolled).toBe(true);
expect(live(taking).map((device) => device.hardwareSerial)).toEqual(["SER-2"]);
taking.driver.setPhysicalDevices([{ ids: [network] }]);
await taking.core.enrollment.add("ios", network);
expect(live(taking)[0]).not.toHaveProperty("hardwareSerial");

const first = await build([{ ids: ["SER-9"] }, { hardwareSerial: "SER-9", ids: [network] }]);
const held = holdInspection(first.driver, 1);
const racing = first.core.enrollment.add("ios", network);
const lost = expect(racing).rejects.toMatchObject({
canonicalId: "SER-9",
reason: "enrolled-under-other-id",
});
await vi.waitFor(() => expect(held.reached).toHaveBeenCalled());
await first.core.enrollment.add("ios", "SER-9");
held.release();
await lost;
expect(live(first).map((device) => device.driverDeviceId)).toEqual(["SER-9"]);

const second = await build([{ hardwareSerial: "SER-1", ids: [network] }, { ids: ["SER-9"] }]);
await second.core.enrollment.add("ios", network);
await second.core.enrollment.add("ios", "SER-9");
const original = second.driver.inspectPhysical.bind(second.driver);
let calls = 0;
vi.spyOn(second.driver, "inspectPhysical").mockImplementation(async (id) => {
calls += 1;
const read = await original(id);
return calls === 2 && read.enrollable ? { ...read, hardwareSerial: "SER-9" } : read;
});
const before = JSON.stringify(live(second));

await expect(second.core.enrollment.add("ios", network)).rejects.toMatchObject({
canonicalId: "SER-9",
reason: "enrolled-under-other-id",
});

expect(JSON.stringify(live(second))).toBe(before);
});

it("names the device in its error when the second read names another device or a read fails", async () => {
const harness = await build();
await harness.core.enrollment.add("ios", UDID);
Expand Down
Loading
Loading