@bugmole/cli 0.4.0

package/src/registry-worker/devices/policy.ts

@@ -0,0 +1,71 @@
+// Who may run on which device cloud.
+import type { CloudDevice } from "../../runtime/device-clouds/types.js";
+import type { Env } from "../core.js";
+import { response } from "../core.js";
+import { getEntitlements } from "../billing/entitlements.js";
+import { canSpend } from "../billing/ledger.js";
+import { flagOn } from "../flags.js";
+
+export type BugmoleDeviceEnv = {
+  BUGMOLE_DEVICE_FARM_ACCESS_KEY_ID?: string;
+  BUGMOLE_DEVICE_FARM_SECRET_ACCESS_KEY?: string;
+  BUGMOLE_DEVICE_FARM_PROJECT_ARN?: string;
+  /** The same keys under their pre-rename secret names, used until they are re-set as BUGMOLE_*. */
+  VALKYRIE_DEVICE_FARM_ACCESS_KEY_ID?: string;
+  VALKYRIE_DEVICE_FARM_SECRET_ACCESS_KEY?: string;
+  /** Test seam for Device Farm calls. */
+  DEVICE_FARM_FETCH?: typeof fetch;
+};
+
+export function bugmoleDeviceCloud(env: Env): { credentials: { accessKeyId: string; secretAccessKey: string }; projectArn: string; fetch?: typeof fetch } | null {
+  const own = env as Env & BugmoleDeviceEnv;
+  const accessKeyId = own.BUGMOLE_DEVICE_FARM_ACCESS_KEY_ID ?? own.VALKYRIE_DEVICE_FARM_ACCESS_KEY_ID;
+  const secretAccessKey = own.BUGMOLE_DEVICE_FARM_SECRET_ACCESS_KEY ?? own.VALKYRIE_DEVICE_FARM_SECRET_ACCESS_KEY;
+  if (!accessKeyId || !secretAccessKey || !own.BUGMOLE_DEVICE_FARM_PROJECT_ARN) return null;
+  return {
+    credentials: { accessKeyId, secretAccessKey },
+    projectArn: own.BUGMOLE_DEVICE_FARM_PROJECT_ARN,
+    ...(own.DEVICE_FARM_FETCH ? { fetch: own.DEVICE_FARM_FETCH } : {}),
+  };
+}
+
+function refused(error: string, code: string, status = 422): Response {
+  return response({ error, code, ...(status === 402 ? { upgradeUrl: "/billing" } : {}) }, status);
+}
+
+/** Null when every device target in a run may be used; otherwise the response to return. */
+export async function deviceTargetsError(
+  env: Env,
+  projectId: string,
+  workspaceId: string | null,
+  targets: CloudDevice[],
+  executionMode: "self" | "cloud",
+): Promise<Response | null> {
+  if (!workspaceId) return refused("This project isn't in a workspace", "no_workspace");
+  if (!(await flagOn(env, workspaceId, "device_clouds"))) return refused("Device clouds aren't available for this workspace yet.", "device_clouds_unavailable");
+  const { features } = await getEntitlements(env, workspaceId);
+  if (!features.deviceClouds) return refused("Real devices and device clouds are included in Business.", "plan_feature", 402);
+  for (const target of targets) {
+    if (target.provider === "bugmole") {
+      if (executionMode !== "cloud") return refused("Bugmole's own devices are only used by runs on Bugmole Cloud.", "bugmole_devices_need_cloud");
+      if (!target.real) return refused("Bugmole's device cloud has real devices only; use a connected cloud for emulators.", "bugmole_real_only");
+      if (!bugmoleDeviceCloud(env)) return refused("Bugmole's device cloud isn't available right now.", "bugmole_devices_unavailable", 503);
+      const spend = await canSpend(env, workspaceId, "device_minute", 1);
+      if (!spend.allowed) return refused(spend.message, "plan_limit", 402);
+    } else {
+      const credential = await env.DB.prepare(`
+        SELECT provider FROM device_cloud_credentials WHERE id = ? AND workspace_id = ? AND revoked_at IS NULL
+      `).bind(target.credentialId ?? "", workspaceId).first<{ provider: string }>();
+      if (!credential || credential.provider !== target.provider) {
+        return refused(`That ${target.provider} connection isn't set up in this workspace.`, "device_credential_missing");
+      }
+    }
+    if (target.appBuildId) {
+      const build = await env.DB.prepare("SELECT platform FROM app_builds WHERE id = ? AND project_id = ? AND deleted_at IS NULL")
+        .bind(target.appBuildId, projectId).first<{ platform: string }>();
+      if (!build) return refused("That app build isn't in this project.", "app_build_missing");
+      if (build.platform !== target.platform) return refused(`That build is for ${build.platform}, not ${target.platform}.`, "app_build_platform");
+    }
+  }
+  return null;
+}

package/src/registry-worker/devices/routes.ts

@@ -0,0 +1,453 @@
+// Device clouds: connections a workspace saves, their device catalogs, app
+// builds, the access a running run gets, and sessions on Bugmole's own
+// device cloud (AWS Device Farm), metered in device minutes.
+import type { CloudDevice, DeviceCredential } from "../../runtime/device-clouds/types.js";
+import { deviceFarmCapabilities } from "../../runtime/device-clouds/device-farm.js";
+import {
+  deviceFarmCall,
+  DeviceFarmError,
+  finishedSession,
+  listDevices,
+  sessionArtifacts,
+  stopSession,
+  uploadApp,
+  type DeviceFarmOptions,
+} from "../../integrations/device-farm.js";
+import type { Env, Principal } from "../core.js";
+import { memberOfProject, memberOfWorkspace, newId, requestJson, response, sha256 } from "../core.js";
+import { getEntitlements } from "../billing/entitlements.js";
+import { canSpend, recordUsage } from "../billing/ledger.js";
+import { registerJob } from "../jobs/index.js";
+import { actorOf, auditProject, recordAudit } from "../org/audit.js";
+import { canStoreSecrets, openSecret, sealSecret } from "../notifications/secrets.js";
+import { matchPath, registerRoutes, type AuthedRouteContext } from "../routes/index.js";
+import { bugmoleDeviceCloud } from "./policy.js";
+
+const PROVIDERS = new Set(["browserstack", "kobiton", "aws_device_farm"]);
+export const MAX_APP_BYTES = 95 * 1024 * 1024;
+/** Device Farm deletes uploads after 30 days. */
+const UPLOAD_REUSE_MS = 25 * 86_400_000;
+const SESSION_MAX_MS = 150 * 60_000;
+
+type Fetcher = typeof fetch;
+
+function providerFetch(env: Env): Fetcher {
+  return (env as Env & { DEVICE_FARM_FETCH?: Fetcher }).DEVICE_FARM_FETCH ?? fetch;
+}
+
+async function manageable(env: Env, principal: Principal, workspaceId: string): Promise<Response | null> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"))) return response({ error: "Only owners and admins can manage device clouds" }, 403);
+  const { features } = await getEntitlements(env, workspaceId);
+  if (!features.deviceClouds) return response({ error: "Device clouds are included in Business.", code: "plan_feature", upgradeUrl: "/billing" }, 402);
+  if (!canStoreSecrets(env)) return response({ error: "Device clouds can't be connected right now." }, 503);
+  return null;
+}
+
+async function credentialFor(env: Env, workspaceId: string, id: string): Promise<(DeviceCredential & { id: string }) | null> {
+  const row = await env.DB.prepare(`
+    SELECT id, provider, username, project_arn AS projectArn, secret_ciphertext AS ciphertext, secret_iv AS iv
+    FROM device_cloud_credentials WHERE id = ? AND workspace_id = ? AND revoked_at IS NULL
+  `).bind(id, workspaceId).first<{ id: string; provider: DeviceCredential["provider"]; username: string; projectArn: string | null; ciphertext: string; iv: string }>();
+  if (!row) return null;
+  return { id: row.id, provider: row.provider, username: row.username, secret: await openSecret(env, row.ciphertext, row.iv), ...(row.projectArn ? { projectArn: row.projectArn } : {}) };
+}
+
+// --- Provider catalogs and connection checks ---------------------------------------------------
+
+export type CatalogDevice = { name: string; platform: "android" | "ios"; osVersion: string; real: boolean; deviceArn?: string; browsers: Array<"chrome" | "safari"> };
+
+function basic(credential: DeviceCredential): string {
+  return `Basic ${btoa(`${credential.username}:${credential.secret}`)}`;
+}
+
+async function catalog(env: Env, credential: DeviceCredential): Promise<CatalogDevice[]> {
+  const doFetch = providerFetch(env);
+  if (credential.provider === "browserstack") {
+    const reply = await doFetch("https://api-cloud.browserstack.com/app-automate/devices.json", { headers: { authorization: basic(credential) } });
+    if (!reply.ok) throw new Error(reply.status === 401 ? "BrowserStack didn't accept the user name and access key" : `BrowserStack answered ${reply.status}`);
+    const devices = await reply.json() as Array<{ os: string; os_version: string; device: string; realMobile?: boolean }>;
+    return devices.map((device) => ({
+      name: device.device,
+      platform: device.os === "ios" ? "ios" : "android",
+      osVersion: device.os_version,
+      real: device.realMobile !== false,
+      browsers: [device.os === "ios" ? "safari" : "chrome"],
+    }));
+  }
+  if (credential.provider === "kobiton") {
+    const reply = await doFetch("https://api.kobiton.com/v1/devices", { headers: { authorization: basic(credential) } });
+    if (!reply.ok) throw new Error(reply.status === 401 ? "Kobiton didn't accept the user name and API key" : `Kobiton answered ${reply.status}`);
+    const body = await reply.json() as { cloudDevices?: Array<Record<string, any>>; privateDevices?: Array<Record<string, any>> };
+    return [...(body.cloudDevices ?? []), ...(body.privateDevices ?? [])].map((device) => ({
+      name: String(device.deviceName),
+      platform: String(device.platformName).toLowerCase() === "ios" ? "ios" : "android",
+      osVersion: String(device.platformVersion ?? ""),
+      real: device.isVirtual !== true,
+      browsers: [String(device.platformName).toLowerCase() === "ios" ? "safari" : "chrome"],
+    }));
+  }
+  const devices = await listDevices({
+    credentials: { accessKeyId: credential.username, secretAccessKey: credential.secret },
+    projectArn: credential.projectArn ?? "",
+    fetch: doFetch,
+  });
+  return devices.map((device) => ({
+    name: device.name,
+    platform: device.platform === "IOS" ? "ios" : "android",
+    osVersion: device.os,
+    real: true,
+    deviceArn: device.arn,
+    browsers: [device.platform === "IOS" ? "safari" : "chrome"],
+  }));
+}
+
+function unique(devices: CatalogDevice[]): CatalogDevice[] {
+  const seen = new Set<string>();
+  return devices
+    .filter((device) => {
+      const key = `${device.platform}|${device.name}|${device.osVersion}|${device.real}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => a.platform.localeCompare(b.platform) || a.name.localeCompare(b.name) || b.osVersion.localeCompare(a.osVersion, undefined, { numeric: true }));
+}
+
+// --- Connections -------------------------------------------------------------------------------
+
+async function listConnections({ env, principal }: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId))) return response({ error: "Workspace scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT id, provider, label, username, project_arn AS projectArn, created_at AS createdAt, last_verified_at AS lastVerifiedAt
+    FROM device_cloud_credentials WHERE workspace_id = ? AND revoked_at IS NULL ORDER BY created_at ASC
+  `).bind(workspaceId).all();
+  const { features } = await getEntitlements(env, workspaceId);
+  return response({
+    available: features.deviceClouds,
+    canManage: await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"),
+    bugmole: { available: features.deviceClouds && Boolean(bugmoleDeviceCloud(env)) },
+    connections: rows.results,
+  });
+}
+
+async function addConnection({ env, principal, request }: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  const denied = await manageable(env, principal, workspaceId);
+  if (denied) return denied;
+  const body = await requestJson(request);
+  const provider = body?.provider;
+  const username = typeof body?.username === "string" ? body.username.trim() : "";
+  const secret = typeof body?.secret === "string" ? body.secret.trim() : "";
+  const projectArn = typeof body?.projectArn === "string" && body.projectArn.trim() ? body.projectArn.trim() : null;
+  const label = typeof body?.label === "string" && body.label.trim() ? body.label.trim().slice(0, 80) : String(provider);
+  if (typeof provider !== "string" || !PROVIDERS.has(provider)) return response({ error: "provider must be browserstack, kobiton or aws_device_farm" }, 422);
+  if (!username || !secret || username.length > 200 || secret.length > 500) return response({ error: "Enter the user name (or access key id) and the key" }, 422);
+  if (provider === "aws_device_farm" && !/^arn:aws:devicefarm:us-west-2:\d{12}:project:[A-Za-z0-9-]+$/.test(projectArn ?? "")) {
+    return response({ error: "Enter the Device Farm project ARN (us-west-2)" }, 422);
+  }
+  const credential = { provider, username, secret, ...(projectArn ? { projectArn } : {}) } as DeviceCredential;
+  // Check it works before saving it.
+  try {
+    await catalog(env, credential);
+  } catch (error) {
+    return response({ error: error instanceof Error ? error.message : "The connection didn't work", code: "device_cloud_rejected" }, 422);
+  }
+  const sealed = await sealSecret(env, secret);
+  const id = newId("dcc");
+  await env.DB.prepare(`
+    INSERT INTO device_cloud_credentials (id, workspace_id, provider, label, username, project_arn, secret_ciphertext, secret_iv, created_by, last_verified_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(id, workspaceId, provider, label, username, projectArn, sealed.ciphertext, sealed.iv, principal.aegisId, new Date().toISOString()).run();
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "device_cloud.connected", targetType: "device_cloud", targetId: id, data: { provider } }, request);
+  return response({ connection: { id, provider, label, username, projectArn } }, 201);
+}
+
+async function removeConnection({ env, principal, request }: AuthedRouteContext, workspaceId: string, id: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"))) return response({ error: "Only owners and admins can manage device clouds" }, 403);
+  const updated = await env.DB.prepare("UPDATE device_cloud_credentials SET revoked_at = ?, secret_ciphertext = '', secret_iv = '' WHERE id = ? AND workspace_id = ? AND revoked_at IS NULL")
+    .bind(new Date().toISOString(), id, workspaceId).run();
+  if ((updated.meta?.changes ?? 0) === 0) return response({ error: "Not found" }, 404);
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "device_cloud.disconnected", targetType: "device_cloud", targetId: id }, request);
+  return response({ removed: true });
+}
+
+async function devicesFor({ env, principal }: AuthedRouteContext, workspaceId: string, id: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId))) return response({ error: "Workspace scope is not allowed" }, 403);
+  try {
+    if (id === "bugmole") {
+      const own = bugmoleDeviceCloud(env);
+      const { features } = await getEntitlements(env, workspaceId);
+      if (!own || !features.deviceClouds) return response({ error: "Bugmole's device cloud isn't available for this workspace" }, 402);
+      return response({ devices: unique(await catalog(env, { provider: "aws_device_farm", username: own.credentials.accessKeyId, secret: own.credentials.secretAccessKey, projectArn: own.projectArn })) });
+    }
+    const credential = await credentialFor(env, workspaceId, id);
+    if (!credential) return response({ error: "Not found" }, 404);
+    const devices = unique(await catalog(env, credential));
+    await env.DB.prepare("UPDATE device_cloud_credentials SET last_verified_at = ? WHERE id = ?").bind(new Date().toISOString(), id).run();
+    return response({ devices });
+  } catch (error) {
+    return response({ error: error instanceof Error ? error.message : "The device cloud didn't answer", code: "device_cloud_unavailable" }, 502);
+  }
+}
+
+// --- App builds ----------------------------------------------------------------------------------
+
+async function uploadBuild({ env, principal, request, url }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  if (!env.ARTIFACTS) return response({ error: "App builds can't be stored right now" }, 503);
+  const platform = url.searchParams.get("platform");
+  const filename = (url.searchParams.get("filename") ?? "").trim();
+  if (platform !== "android" && platform !== "ios") return response({ error: "platform must be android or ios" }, 422);
+  const extension = platform === "android" ? /\.(apk|aab)$/i : /\.ipa$/i;
+  if (!/^[A-Za-z0-9._ -]{1,120}$/.test(filename) || !extension.test(filename)) {
+    return response({ error: platform === "android" ? "Upload an .apk or .aab file" : "Upload an .ipa file" }, 422);
+  }
+  const declared = Number(request.headers.get("content-length") ?? NaN);
+  if (Number.isFinite(declared) && declared > MAX_APP_BYTES) return response({ error: "App builds can be up to 95 MB" }, 413);
+  const bytes = new Uint8Array(await request.arrayBuffer());
+  if (bytes.byteLength === 0) return response({ error: "The file is empty" }, 422);
+  if (bytes.byteLength > MAX_APP_BYTES) return response({ error: "App builds can be up to 95 MB" }, 413);
+  // APK, AAB and IPA are all zip files.
+  if (bytes[0] !== 0x50 || bytes[1] !== 0x4b) return response({ error: "That isn't an app package" }, 422);
+  const digest = [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  const id = newId("app");
+  const objectKey = `projects/${encodeURIComponent(projectId)}/app-builds/${id}/${filename}`;
+  await env.ARTIFACTS.put(objectKey, bytes, { httpMetadata: { contentType: "application/octet-stream" } });
+  await env.DB.prepare(`
+    INSERT INTO app_builds (id, project_id, platform, filename, object_key, size_bytes, sha256, uploaded_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(id, projectId, platform, filename, objectKey, bytes.byteLength, digest, principal.aegisId).run();
+  await auditProject(env, principal, projectId, { action: "app_build.uploaded", targetType: "app_build", targetId: id, data: { platform, filename } }, request);
+  return response({ build: { id, platform, filename, sizeBytes: bytes.byteLength, sha256: digest } }, 201);
+}
+
+async function listBuilds({ env, principal }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT id, platform, filename, size_bytes AS sizeBytes, created_at AS createdAt FROM app_builds
+    WHERE project_id = ? AND deleted_at IS NULL ORDER BY created_at DESC LIMIT 50
+  `).bind(projectId).all();
+  return response({ builds: rows.results });
+}
+
+async function deleteBuild({ env, principal, request }: AuthedRouteContext, projectId: string, id: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const build = await env.DB.prepare("SELECT object_key AS key FROM app_builds WHERE id = ? AND project_id = ? AND deleted_at IS NULL").bind(id, projectId).first<{ key: string }>();
+  if (!build) return response({ error: "Not found" }, 404);
+  await env.ARTIFACTS?.delete(build.key);
+  await env.DB.prepare("UPDATE app_builds SET deleted_at = ? WHERE id = ?").bind(new Date().toISOString(), id).run();
+  await auditProject(env, principal, projectId, { action: "app_build.deleted", targetType: "app_build", targetId: id }, request);
+  return response({ deleted: true });
+}
+
+// --- What a running run may use --------------------------------------------------------------
+
+type RunRow = { id: string; projectId: string; workspaceId: string | null; status: string; workerId: string | null; targetsJson: string | null };
+
+async function runFor(env: Env, principal: Principal, runId: string): Promise<RunRow | Response> {
+  const run = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, workspace_id AS workspaceId, status, worker_id AS workerId, targets_json AS targetsJson
+    FROM runs WHERE id = ?
+  `).bind(runId).first<RunRow>();
+  if (!run) return response({ error: "Run not found" }, 404);
+  const allowed = principal.runner
+    ? principal.runner.kind === "run" && principal.runner.id === runId
+    : await memberOfProject(env, principal, run.projectId, "project.write");
+  if (!allowed) return response({ error: "Run not found" }, 404);
+  // Credentials are only handed out while a worker is actually running the run.
+  if (run.status !== "running" || !run.workerId) return response({ error: "The run isn't running" }, 409);
+  return run;
+}
+
+function cloudTargets(run: RunRow): CloudDevice[] {
+  const targets = run.targetsJson ? JSON.parse(run.targetsJson) as Array<Record<string, unknown>> : [];
+  return targets.filter((target) => target.kind === "device") as unknown as CloudDevice[];
+}
+
+async function deviceAccess({ env, principal }: AuthedRouteContext, runId: string): Promise<Response> {
+  const run = await runFor(env, principal, runId);
+  if (run instanceof Response) return run;
+  const targets = cloudTargets(run);
+  const credentials: Record<string, DeviceCredential> = {};
+  for (const credentialId of new Set(targets.map((target) => target.credentialId).filter((id): id is string => Boolean(id)))) {
+    const credential = run.workspaceId ? await credentialFor(env, run.workspaceId, credentialId) : null;
+    if (credential) {
+      const { id: _id, ...rest } = credential;
+      credentials[credentialId] = rest;
+    }
+  }
+  const buildIds = [...new Set(targets.map((target) => target.appBuildId).filter((id): id is string => Boolean(id)))];
+  const appBuilds = [];
+  for (const id of buildIds) {
+    const build = await env.DB.prepare("SELECT id, platform, filename, sha256, object_key AS objectKey FROM app_builds WHERE id = ? AND project_id = ? AND deleted_at IS NULL")
+      .bind(id, run.projectId).first();
+    if (build) appBuilds.push(build);
+  }
+  return response({
+    credentials,
+    appBuilds,
+    // Bugmole's own devices are opened by the registry, and only for runs on Bugmole Cloud.
+    bugmole: Boolean(principal.runner) && targets.some((target) => target.provider === "bugmole"),
+  });
+}
+
+// --- Bugmole's own device cloud -------------------------------------------------------------
+
+function ownOptions(env: Env): DeviceFarmOptions | null {
+  return bugmoleDeviceCloud(env);
+}
+
+async function appArnFor(env: Env, options: DeviceFarmOptions, projectId: string, buildId: string): Promise<string> {
+  const build = await env.DB.prepare("SELECT platform, filename, object_key AS key, provider_refs_json AS refs FROM app_builds WHERE id = ? AND project_id = ? AND deleted_at IS NULL")
+    .bind(buildId, projectId).first<{ platform: "android" | "ios"; filename: string; key: string; refs: string }>();
+  if (!build) throw new DeviceFarmError(404, "AppBuildMissing", "That app build isn't in this project");
+  const refs = JSON.parse(build.refs || "{}") as { bugmoleDeviceFarm?: { arn: string; at: number } };
+  if (refs.bugmoleDeviceFarm && Date.now() - refs.bugmoleDeviceFarm.at < UPLOAD_REUSE_MS) return refs.bugmoleDeviceFarm.arn;
+  const object = await env.ARTIFACTS?.get(build.key);
+  if (!object) throw new DeviceFarmError(404, "AppBuildMissing", "The app build's file is missing");
+  const bytes = new Uint8Array(await new Response(object.body).arrayBuffer());
+  const arn = await uploadApp(options, { name: build.filename, platform: build.platform, bytes });
+  refs.bugmoleDeviceFarm = { arn, at: Date.now() };
+  await env.DB.prepare("UPDATE app_builds SET provider_refs_json = ? WHERE id = ?").bind(JSON.stringify(refs), buildId).run();
+  return arn;
+}
+
+async function openBugmoleDevice({ env, principal, request }: AuthedRouteContext, runId: string): Promise<Response> {
+  if (!principal.runner) return response({ error: "Not allowed" }, 403);
+  const run = await runFor(env, principal, runId);
+  if (run instanceof Response) return run;
+  const options = ownOptions(env);
+  if (!options || !run.workspaceId) return response({ error: "Bugmole's device cloud isn't available" }, 503);
+  const body = await requestJson(request);
+  const asked = body?.device as CloudDevice | undefined;
+  const target = cloudTargets(run).find((item) => item.provider === "bugmole" && item.deviceName === asked?.deviceName
+    && (item.osVersion ?? "") === (asked?.osVersion ?? "") && (item.browserName ?? "") === (asked?.browserName ?? ""));
+  if (!target) return response({ error: "That device isn't one of this run's targets" }, 422);
+  const spend = await canSpend(env, run.workspaceId, "device_minute", 1);
+  if (!spend.allowed) return response({ error: spend.message, code: "plan_limit" }, 402);
+  try {
+    const deviceArn = target.deviceArn ?? (await listDevices(options)).find((device) =>
+      device.name.toLowerCase() === target.deviceName.toLowerCase() && (!target.osVersion || device.os === target.osVersion)
+      && device.platform === (target.platform === "ios" ? "IOS" : "ANDROID"))?.arn;
+    if (!deviceArn) return response({ error: `No ${target.deviceName} is available` }, 422);
+    const appArn = !target.browserName && target.appBuildId ? await appArnFor(env, options, run.projectId, target.appBuildId) : undefined;
+    const name = typeof body?.name === "string" ? body.name.slice(0, 200) : runId;
+    const created = await deviceFarmCall<{ remoteAccessSession: { arn: string } }>(options, "CreateRemoteAccessSession", {
+      projectArn: options.projectArn,
+      deviceArn,
+      name,
+      ...(appArn ? { appArn } : {}),
+      configuration: { parameters: { "appium:version": "3" } },
+    });
+    const id = newId("vds");
+    await env.DB.prepare(`
+      INSERT INTO bugmole_device_sessions (id, run_id, project_id, workspace_id, device_name, session_arn) VALUES (?, ?, ?, ?, ?, ?)
+    `).bind(id, runId, run.projectId, run.workspaceId, target.deviceName, created.remoteAccessSession.arn).run();
+    return response({ sessionId: id, status: "starting", capabilities: deviceFarmCapabilities(target) }, 201);
+  } catch (error) {
+    return response({ error: error instanceof Error ? error.message : "Device Farm didn't start a device" }, 502);
+  }
+}
+
+async function sessionRow(env: Env, runId: string, sessionId: string) {
+  return env.DB.prepare("SELECT * FROM bugmole_device_sessions WHERE id = ? AND run_id = ?").bind(sessionId, runId)
+    .first<{ id: string; run_id: string; project_id: string; workspace_id: string; session_arn: string; status: string; metered_minutes: number | null; billed_at: string | null }>();
+}
+
+async function bugmoleDeviceStatus({ env, principal }: AuthedRouteContext, runId: string, sessionId: string): Promise<Response> {
+  if (!principal.runner) return response({ error: "Not allowed" }, 403);
+  const run = await runFor(env, principal, runId);
+  if (run instanceof Response) return run;
+  const session = await sessionRow(env, runId, sessionId);
+  const options = ownOptions(env);
+  if (!session || !options) return response({ error: "Not found" }, 404);
+  const remote = (await deviceFarmCall<{ remoteAccessSession: any }>(options, "GetRemoteAccessSession", { arn: session.session_arn })).remoteAccessSession;
+  const hubUrl = remote.endpoints?.remoteDriverEndpoint;
+  if (remote.status === "RUNNING" && hubUrl) {
+    await env.DB.prepare("UPDATE bugmole_device_sessions SET status = 'running' WHERE id = ? AND status = 'starting'").bind(sessionId).run();
+    return response({ status: "running", hubUrl });
+  }
+  if (remote.status === "COMPLETED" || remote.result === "ERRORED" || remote.result === "FAILED") {
+    return response({ status: "failed", error: remote.message ?? "The device session ended before it started" });
+  }
+  return response({ status: "starting" });
+}
+
+/** Stops a session and bills its minutes once. */
+export async function finishBugmoleDevice(env: Env, sessionId: string, waitMs = 60_000): Promise<{ meteredMinutes: number | null; videoUrl?: string }> {
+  const session = await env.DB.prepare("SELECT * FROM bugmole_device_sessions WHERE id = ?").bind(sessionId)
+    .first<{ id: string; run_id: string; project_id: string; workspace_id: string; session_arn: string; billed_at: string | null }>();
+  const options = ownOptions(env);
+  if (!session || !options) return { meteredMinutes: null };
+  await stopSession(options, session.session_arn).catch(() => undefined);
+  const done = await finishedSession(options, session.session_arn, Math.min(5_000, waitMs), waitMs);
+  const video = (await sessionArtifacts(options, session.session_arn).catch(() => [])).find((artifact) => artifact.type === "VIDEO");
+  if (done.status !== "COMPLETED" || done.meteredMinutes === undefined) {
+    await env.DB.prepare("UPDATE bugmole_device_sessions SET status = 'stopping' WHERE id = ?").bind(sessionId).run();
+    return { meteredMinutes: null, ...(video ? { videoUrl: video.url } : {}) };
+  }
+  const minutes = Math.ceil(done.meteredMinutes);
+  if (!session.billed_at && minutes > 0) {
+    await recordUsage(env, {
+      workspaceId: session.workspace_id,
+      projectId: session.project_id,
+      runId: session.run_id,
+      kind: "device_minute",
+      quantity: minutes,
+      source: "device_farm",
+      idempotencyKey: `devicefarm:${await sha256(session.session_arn)}`,
+      meta: { sessionId },
+    });
+  }
+  await env.DB.prepare("UPDATE bugmole_device_sessions SET status = 'finished', metered_minutes = ?, billed_at = COALESCE(billed_at, ?), finished_at = ? WHERE id = ?")
+    .bind(minutes, new Date().toISOString(), new Date().toISOString(), sessionId).run();
+  return { meteredMinutes: minutes, ...(video ? { videoUrl: video.url } : {}) };
+}
+
+async function finishDevice({ env, principal }: AuthedRouteContext, runId: string, sessionId: string): Promise<Response> {
+  if (!principal.runner) return response({ error: "Not allowed" }, 403);
+  const run = await runFor(env, principal, runId);
+  if (run instanceof Response) return run;
+  if (!(await sessionRow(env, runId, sessionId))) return response({ error: "Not found" }, 404);
+  const result = await finishBugmoleDevice(env, sessionId);
+  return response({ links: [], ...(result.videoUrl ? { videoUrl: result.videoUrl } : {}), ...(result.meteredMinutes !== null ? { meteredMinutes: result.meteredMinutes } : {}) });
+}
+
+/** Sessions a runner never finished (it crashed or was stopped) are stopped and billed. */
+export async function sweepDeviceSessions(env: Env, now = new Date()): Promise<number> {
+  const rows = await env.DB.prepare(`
+    SELECT s.id FROM bugmole_device_sessions s LEFT JOIN runs r ON r.id = s.run_id
+    WHERE s.status IN ('starting', 'running', 'stopping')
+      AND (s.status = 'stopping' OR r.status IS NULL OR r.status NOT IN ('queued', 'running') OR s.created_at < ?)
+  `).bind(new Date(now.getTime() - SESSION_MAX_MS).toISOString().replace("T", " ").slice(0, 19)).all<{ id: string }>();
+  for (const row of rows.results) await finishBugmoleDevice(env, row.id, 0).catch((error) => console.error("[devices] sweep failed", error));
+  return rows.results.length;
+}
+
+registerJob("minute", "device-session-sweep", async (env, _ctx, now) => {
+  if (ownOptions(env)) await sweepDeviceSessions(env, now);
+});
+
+registerRoutes(async (context) => {
+  const { request, url } = context;
+  let params = matchPath(url.pathname, "/api/workspaces/:workspaceId/device-clouds");
+  if (params && request.method === "GET") return listConnections(context, params.workspaceId);
+  if (params && request.method === "POST") return addConnection(context, params.workspaceId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/device-clouds/:connectionId");
+  if (params && request.method === "DELETE") return removeConnection(context, params.workspaceId, params.connectionId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/device-clouds/:connectionId/devices");
+  if (params && request.method === "GET") return devicesFor(context, params.workspaceId, params.connectionId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/app-builds");
+  if (params && request.method === "GET") return listBuilds(context, params.projectId);
+  if (params && request.method === "PUT") return uploadBuild(context, params.projectId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/app-builds/:buildId");
+  if (params && request.method === "DELETE") return deleteBuild(context, params.projectId, params.buildId);
+  params = matchPath(url.pathname, "/api/runs/:runId/device-access");
+  if (params && request.method === "GET") return deviceAccess(context, params.runId);
+  params = matchPath(url.pathname, "/api/runs/:runId/device-sessions");
+  if (params && request.method === "POST") return openBugmoleDevice(context, params.runId);
+  params = matchPath(url.pathname, "/api/runs/:runId/device-sessions/:sessionId");
+  if (params && request.method === "GET") return bugmoleDeviceStatus(context, params.runId, params.sessionId);
+  params = matchPath(url.pathname, "/api/runs/:runId/device-sessions/:sessionId/finish");
+  if (params && request.method === "POST") return finishDevice(context, params.runId, params.sessionId);
+  return null;
+});
+