@xenon-device-management/xenon 2.13.2 → 2.15.0

package/lib/test/unit/ai-rate-limit.spec.js

@@ -0,0 +1,126 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const chai_1 = require("chai");
+const AIService_1 = require("../../src/services/AIService");
+const CircuitBreaker_1 = require("../../src/services/CircuitBreaker");
+const fake_ai_provider_1 = require("../helpers/fake-ai-provider");
+/**
+ * A rate-limited provider (HTTP 429) is a failed call, whichever provider it
+ * is.
+ *
+ * Gemini's provider answered a 429 with the string
+ * 'CONNECTION_OK_RATE_LIMITED' instead of failing, so a failed session's AI
+ * analysis was saved as that string and shown on the session page, in the
+ * copied report and in bug reports. The circuit breaker counted it as a
+ * success, so it never stopped calling a provider that kept refusing. Only the
+ * visual assertion and the screen description checked for the string.
+ */
+describe('AI provider rate limits', () => {
+    const ai = (0, fake_ai_provider_1.useFakeAiProviders)();
+    const FAILURE = {
+        sessionId: 'sess-rate-limit',
+        failureReason: 'An element could not be located on the page',
+        commandLogs: [],
+        deviceLogs: [],
+    };
+    const SCREEN = 'c2NyZWVuc2hvdA==';
+    const failureOf = (p) => p.then((value) => {
+        throw new Error(`expected a failure, got ${JSON.stringify(value)}`);
+    }, (e) => e);
+    for (const provider of fake_ai_provider_1.PROVIDERS) {
+        describe(provider, () => {
+            let service;
+            let model;
+            beforeEach(() => {
+                ({ model } = ai.use(provider));
+                ai.answer({ status: 429 });
+                service = new AIService_1.AIService();
+            });
+            it('gives no failure analysis', () => __awaiter(void 0, void 0, void 0, function* () {
+                (0, chai_1.expect)(yield service.analyzeFailure(FAILURE)).to.equal(null);
+                (0, chai_1.expect)(ai.calls).to.have.length(1);
+            }));
+            it('counts against the circuit breaker, which stops calling after five', () => __awaiter(void 0, void 0, void 0, function* () {
+                for (let i = 0; i < 6; i++)
+                    yield service.analyzeFailure(FAILURE);
+                (0, chai_1.expect)(ai.calls).to.have.length(5);
+                const breaker = CircuitBreaker_1.CIRCUIT_BREAKERS.snapshot().find((b) => b.key === `ai:${provider}:${model}`);
+                (0, chai_1.expect)(breaker === null || breaker === void 0 ? void 0 : breaker.state).to.equal('open');
+            }));
+            it('fails a visual assertion, saying the provider is rate-limited', () => __awaiter(void 0, void 0, void 0, function* () {
+                const err = yield failureOf(service.assertVisual(SCREEN, 'The cart is empty'));
+                (0, chai_1.expect)(err.message).to.match(/rate-limited/);
+                (0, chai_1.expect)(err.message).to.match(/not checked/);
+            }));
+            it('gives no screen description, saying the provider is rate-limited', () => __awaiter(void 0, void 0, void 0, function* () {
+                const err = yield failureOf(service.describeScreen(SCREEN));
+                (0, chai_1.expect)(err.message).to.match(/rate-limited/);
+            }));
+            it('fails a locator test, saying the provider is rate-limited', () => __awaiter(void 0, void 0, void 0, function* () {
+                const err = yield failureOf(service.visualFind(SCREEN, 'the cart icon', { throwOnError: true }));
+                (0, chai_1.expect)(err.message).to.match(/rate-limited/);
+            }));
+            it('finds nothing for a healing or an ai-icon search', () => __awaiter(void 0, void 0, void 0, function* () {
+                (0, chai_1.expect)(yield service.visualFind(SCREEN, 'the cart icon')).to.equal(null);
+                (0, chai_1.expect)(yield service.healLocator({ selector: '//x', strategy: 'xpath', xml: '<hierarchy/>' })).to.equal(null);
+            }));
+            it('says in plain words, once the breaker has opened, that it is waiting', () => __awaiter(void 0, void 0, void 0, function* () {
+                for (let i = 0; i < 5; i++)
+                    yield failureOf(service.describeScreen(SCREEN));
+                // The sixth isn't sent. Testers see this (Omni-Scan, Test locator).
+                const described = yield failureOf(service.describeScreen(SCREEN));
+                (0, chai_1.expect)(described.message).to.match(/has been failing/);
+                (0, chai_1.expect)(described.message).to.match(/again in \d+ s/);
+                (0, chai_1.expect)(described.message).not.to.match(/circuit|ai:/i);
+                const asserted = yield failureOf(service.assertVisual(SCREEN, 'The cart is empty'));
+                (0, chai_1.expect)(asserted.message).to.match(/has been failing/);
+                (0, chai_1.expect)(asserted.message).to.match(/not checked/);
+                (0, chai_1.expect)(asserted.message).not.to.match(/circuit|ai:/i);
+                (0, chai_1.expect)(ai.calls).to.have.length(5);
+            }));
+            it('fails the connection test, saying the provider is rate-limited', () => __awaiter(void 0, void 0, void 0, function* () {
+                const result = yield service.testConnection({});
+                (0, chai_1.expect)(result.success).to.equal(false);
+                (0, chai_1.expect)(result.message).to.match(/rate-limited or out of quota/);
+            }));
+        });
+    }
+    it('gemini: an error that only mentions 429 is not a rate limit', () => __awaiter(void 0, void 0, void 0, function* () {
+        ai.use('gemini');
+        ai.answer({
+            status: 400,
+            message: 'The input token count (1429384) exceeds the maximum number of tokens allowed.',
+        });
+        const service = new AIService_1.AIService();
+        const err = yield failureOf(service.describeScreen(SCREEN));
+        (0, chai_1.expect)(err.message).not.to.match(/rate-limited/);
+        // A 400 is the request's fault: the breaker doesn't count it, so all six are sent.
+        for (let i = 0; i < 5; i++)
+            yield service.analyzeFailure(FAILURE);
+        (0, chai_1.expect)(ai.calls).to.have.length(6);
+    }));
+    it('ollama: is asked again as soon as it is back', () => __awaiter(void 0, void 0, void 0, function* () {
+        ai.use('ollama');
+        ai.ollamaUp(false);
+        const service = new AIService_1.AIService();
+        (0, chai_1.expect)(yield service.analyzeFailure(FAILURE)).to.equal(null);
+        ai.ollamaUp(true);
+        ai.answer({ text: 'Root Cause: the app crashed.' });
+        (0, chai_1.expect)(yield service.analyzeFailure(FAILURE)).to.equal('Root Cause: the app crashed.');
+    }));
+    it("still gives a provider's real answer", () => __awaiter(void 0, void 0, void 0, function* () {
+        ai.use('gemini');
+        ai.answer({ text: 'Root Cause: the Login button was covered by a dialog.' });
+        (0, chai_1.expect)(yield new AIService_1.AIService().analyzeFailure(FAILURE)).to.equal('Root Cause: the Login button was covered by a dialog.');
+    }));
+});

package/lib/test/unit/android-h264-viewers.spec.js

@@ -0,0 +1,272 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const http_1 = __importDefault(require("http"));
+const chai_1 = require("chai");
+const typedi_1 = require("typedi");
+const ws_1 = require("ws");
+const AndroidH264StreamService_1 = __importDefault(require("../../src/device-managers/android/AndroidH264StreamService"));
+const h264StreamWs_1 = require("../../src/app/ws/h264StreamWs");
+const PluginContext_1 = require("../../src/PluginContext");
+const container_registration_1 = require("../helpers/container-registration");
+const loopbackServer_1 = require("../helpers/loopbackServer");
+/**
+ * Which viewers an H.264 capture outlives once a page has asked for MJPEG.
+ *
+ * A page whose H.264 player fails (a device control page, or a Live devices
+ * tile) asks for MJPEG (`stream/start` with `player: 'mjpeg'`). The phone may
+ * have other viewers still playing its H.264 preview: another tile, another
+ * tab, another admin. Ending the capture under them froze their picture on
+ * its last frame. So the capture ends when nobody watches it: at once if
+ * nobody does, else the moment the last one leaves, and never after the
+ * ten-minute idle wait an unwatched H.264 capture otherwise gets.
+ */
+const UDID = 'R58M123';
+const key = (n) => ({ type: 'key', data: Buffer.from([n]), ptsMs: n });
+// The capture seam (openCapture) is stubbed, as in android-h264-service.spec.ts.
+function make() {
+    const svc = Object.create(AndroidH264StreamService_1.default.prototype);
+    svc.sessions = new Map();
+    svc.startPromises = new Map();
+    svc.scrcpyIncompatible = new Set();
+    return svc;
+}
+/** A service whose next capture is under the test's control. */
+function withCapture() {
+    const svc = make();
+    const capture = {
+        kills: 0,
+        push: () => undefined,
+    };
+    let release = () => undefined;
+    let held = false;
+    svc.openCapture = (_udid, onPacket) => __awaiter(this, void 0, void 0, function* () {
+        capture.push = onPacket;
+        if (held)
+            yield new Promise((r) => (release = r));
+        onPacket({ type: 'config', data: Buffer.from([0]), ptsMs: 0 });
+        return {
+            kill: () => {
+                capture.kills += 1;
+            },
+        };
+    });
+    return {
+        svc,
+        capture,
+        /** Keep the next capture starting until `finishStart()`. */
+        holdStart: () => (held = true),
+        finishStart: () => release(),
+    };
+}
+/** A viewer's socket: what it received, and how it leaves. */
+function watch(mux) {
+    const got = [];
+    const leave = mux.addClient((p) => got.push(p.type));
+    return { got, leave };
+}
+/** Waits for `done()`, a few milliseconds at a time: a socket's close lands on the server later. */
+function until(done, what) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const by = Date.now() + 2000;
+        while (!done()) {
+            if (Date.now() > by)
+                throw new Error(`timed out waiting until ${what}`);
+            yield new Promise((r) => setTimeout(r, 5));
+        }
+    });
+}
+describe('AndroidH264StreamService: a page that asks for MJPEG', () => {
+    const loopback = (0, loopbackServer_1.loopbackServers)();
+    let restoreContainer;
+    beforeEach(() => {
+        restoreContainer = (0, container_registration_1.saveRegistrations)(PluginContext_1.PluginContext);
+        typedi_1.Container.set(PluginContext_1.PluginContext, { pluginArgs: {} });
+    });
+    afterEach(() => __awaiter(void 0, void 0, void 0, function* () {
+        restoreContainer();
+        yield loopback.closeAll();
+    }));
+    it('ends the H.264 capture at once when nobody watches it', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture } = withCapture();
+        yield svc.start(UDID);
+        yield svc.endWhenUnwatched(UDID);
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+        (0, chai_1.expect)(svc.getMultiplexer(UDID)).to.equal(undefined);
+    }));
+    it('keeps it for a viewer still playing it', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture } = withCapture();
+        const viewer = watch(yield svc.start(UDID));
+        yield svc.endWhenUnwatched(UDID);
+        (0, chai_1.expect)(capture.kills).to.equal(0);
+        capture.push(key(1));
+        (0, chai_1.expect)(viewer.got).to.deep.equal(['config', 'key']);
+    }));
+    it('ends it the moment its last viewer leaves, not after the idle wait', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture } = withCapture();
+        const mux = yield svc.start(UDID);
+        const a = watch(mux);
+        const b = watch(mux);
+        yield svc.endWhenUnwatched(UDID);
+        a.leave();
+        (0, chai_1.expect)(capture.kills, 'b still plays it').to.equal(0);
+        b.leave();
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+        (0, chai_1.expect)(svc.getMultiplexer(UDID)).to.equal(undefined);
+    }));
+    it('serves a viewer who joins before then, and ends when they leave too', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture } = withCapture();
+        const a = watch(yield svc.start(UDID));
+        yield svc.endWhenUnwatched(UDID);
+        const late = watch(yield svc.start(UDID));
+        a.leave();
+        (0, chai_1.expect)(capture.kills).to.equal(0);
+        capture.push(key(2));
+        (0, chai_1.expect)(late.got).to.include('key');
+        late.leave();
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+    }));
+    it('does nothing when no H.264 capture runs for the phone', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture } = withCapture();
+        yield svc.endWhenUnwatched(UDID);
+        (0, chai_1.expect)(capture.kills).to.equal(0);
+        (0, chai_1.expect)(svc.getMultiplexer(UDID)).to.equal(undefined);
+    }));
+    it('leaves a capture that is still starting to the viewer starting it', () => __awaiter(void 0, void 0, void 0, function* () {
+        // A tile's socket starts the capture it is about to watch: ending it
+        // mid-start would leave that capture running with nothing to stop it.
+        const { svc, capture, holdStart, finishStart } = withCapture();
+        holdStart();
+        const starting = svc.start(UDID);
+        yield Promise.resolve();
+        yield svc.endWhenUnwatched(UDID);
+        finishStart();
+        const viewer = watch(yield starting);
+        (0, chai_1.expect)(capture.kills).to.equal(0);
+        viewer.leave();
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+    }));
+    it('ends a capture whose viewer never came at the watchdog’s next look', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture, holdStart, finishStart } = withCapture();
+        holdStart();
+        const starting = svc.start(UDID);
+        yield Promise.resolve();
+        yield svc.endWhenUnwatched(UDID);
+        finishStart();
+        yield starting;
+        svc.sweep(Date.now());
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+    }));
+    it('keeps the idle wait for a capture no page asked to end', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture } = withCapture();
+        yield svc.start(UDID);
+        svc.sweep(Date.now());
+        svc.sweep(Date.now() + 60000);
+        (0, chai_1.expect)(capture.kills).to.equal(0);
+        (0, chai_1.expect)(svc.getMultiplexer(UDID)).to.not.equal(undefined);
+    }));
+    it('does not end a newer capture when an older one’s last viewer leaves', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { svc, capture } = withCapture();
+        const old = watch(yield svc.start(UDID));
+        yield svc.endWhenUnwatched(UDID);
+        yield svc.stop(UDID); // a recording took the phone, say
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+        yield svc.start(UDID);
+        old.leave();
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+        (0, chai_1.expect)(svc.getMultiplexer(UDID)).to.not.equal(undefined);
+    }));
+    it('ends it when the last viewer’s H.264 socket closes', () => __awaiter(void 0, void 0, void 0, function* () {
+        // The socket route (h264StreamWs.ts), as a tile's player opens and closes it.
+        const { svc, capture } = withCapture();
+        const server = yield loopback.serve(http_1.default.createServer());
+        (0, h264StreamWs_1.attachH264Ws)(server, {
+            redeem: () => __awaiter(void 0, void 0, void 0, function* () { return ({ actorId: 'usr_alice' }); }),
+            startStream: (udid) => svc.start(udid),
+        });
+        const { port } = server.address();
+        // The config packet is sent the moment the socket joins the multiplexer.
+        const viewer = () => new Promise((resolve, reject) => {
+            const ws = new ws_1.WebSocket(`ws://127.0.0.1:${port}/xenon/api/control/${UDID}/stream/h264?ticket=t`);
+            ws.once('message', () => resolve(ws));
+            ws.once('error', reject);
+        });
+        const tile = yield viewer();
+        const otherTab = yield viewer();
+        const viewers = () => { var _a, _b; return (_b = (_a = svc.getMultiplexer(UDID)) === null || _a === void 0 ? void 0 : _a.clientCount) !== null && _b !== void 0 ? _b : 0; };
+        yield svc.endWhenUnwatched(UDID);
+        tile.close();
+        yield until(() => viewers() === 1, 'the tile’s socket has left');
+        (0, chai_1.expect)(capture.kills, 'the other tab still plays it').to.equal(0);
+        otherTab.close();
+        yield until(() => capture.kills === 1, 'the capture has ended');
+        (0, chai_1.expect)(svc.getMultiplexer(UDID)).to.equal(undefined);
+    }));
+});
+/**
+ * A capture stopped while viewers still play it: a recording starting on the
+ * phone (ensureMjpegForRecording), or a stream/stop. Their sockets stayed open
+ * with no frames, so the picture froze on its last frame and the page never
+ * fell back to MJPEG.
+ */
+describe('AndroidH264StreamService: a capture stopped under its viewers', () => {
+    const loopback = (0, loopbackServer_1.loopbackServers)();
+    let restoreContainer;
+    beforeEach(() => {
+        restoreContainer = (0, container_registration_1.saveRegistrations)(PluginContext_1.PluginContext);
+        typedi_1.Container.set(PluginContext_1.PluginContext, { pluginArgs: {} });
+    });
+    afterEach(() => __awaiter(void 0, void 0, void 0, function* () {
+        restoreContainer();
+        yield loopback.closeAll();
+    }));
+    it('closes its viewers’ sockets with 1012 when the capture is stopped under them', () => __awaiter(void 0, void 0, void 0, function* () {
+        // 1012 says the stream ended: the player shows MJPEG, without asking the
+        // server to end an H.264 capture that is already gone.
+        const { svc, capture } = withCapture();
+        const server = yield loopback.serve(http_1.default.createServer());
+        (0, h264StreamWs_1.attachH264Ws)(server, {
+            redeem: () => __awaiter(void 0, void 0, void 0, function* () { return ({ actorId: 'usr_alice' }); }),
+            startStream: (udid) => svc.start(udid),
+        });
+        const { port } = server.address();
+        const sockets = [];
+        // How the socket ended, or 'still open' if it hadn't within 2 s.
+        const viewer = () => new Promise((resolve, reject) => {
+            const ws = new ws_1.WebSocket(`ws://127.0.0.1:${port}/xenon/api/control/${UDID}/stream/h264?ticket=t`);
+            sockets.push(ws);
+            const closed = new Promise((r) => {
+                const timer = setTimeout(() => r('still open'), 2000);
+                ws.once('close', (code, reason) => {
+                    clearTimeout(timer);
+                    r([code, reason.toString()]);
+                });
+            });
+            ws.once('message', () => resolve({ closed }));
+            ws.once('error', reject);
+        });
+        try {
+            const tile = yield viewer();
+            const otherTab = yield viewer();
+            yield svc.stop(UDID);
+            (0, chai_1.expect)(yield tile.closed).to.deep.equal([1012, 'stream ended']);
+            (0, chai_1.expect)(yield otherTab.closed).to.deep.equal([1012, 'stream ended']);
+        }
+        finally {
+            sockets.forEach((ws) => ws.terminate());
+        }
+        (0, chai_1.expect)(capture.kills).to.equal(1);
+    }));
+});

package/lib/test/unit/android-preview-hold.spec.js

@@ -54,6 +54,7 @@ const device_store_1 = require("../../src/data-service/device-store");
 const recording_store_1 = require("../../src/services/recording/recording-store");
 const AndroidStreamService_1 = __importDefault(require("../../src/device-managers/android/AndroidStreamService"));
 const AndroidH264StreamService_1 = __importDefault(require("../../src/device-managers/android/AndroidH264StreamService"));
+const H264Multiplexer_1 = require("../../src/device-managers/android/H264Multiplexer");
 const previewHold_1 = require("../../src/device-managers/android/previewHold");
 const UDID = 'android-1';
 const HOLD = `manual_user-1_${UDID}`;
@@ -126,7 +127,7 @@ describe('Android live-preview hold', () => {
         it('releases the hold once nobody has watched for 10 minutes', () => __awaiter(void 0, void 0, void 0, function* () {
             const svc = new AndroidH264StreamService_1.default();
             const kill = sinon_1.default.spy();
-            svc.sessions.set(UDID, { status: 'running', mux: { clientCount: 0 }, capture: { kill } });
+            svc.sessions.set(UDID, { status: 'running', mux: new H264Multiplexer_1.H264Multiplexer(), capture: { kill } });
             yield clock.tickAsync(60000); // first sweep notes it is empty
             yield clock.tickAsync(11 * 60000);
             (0, chai_1.expect)(kill.called, 'capture stopped').to.equal(true);
@@ -137,7 +138,7 @@ describe('Android live-preview hold', () => {
             const svc = new AndroidH264StreamService_1.default();
             svc.sessions.set(UDID, {
                 status: 'running',
-                mux: { clientCount: 0 },
+                mux: new H264Multiplexer_1.H264Multiplexer(),
                 capture: { kill() { } },
             });
             yield clock.tickAsync(12 * 60000);

package/lib/test/unit/apikeys-router.spec.js

@@ -0,0 +1,84 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const chai_1 = require("chai");
+const sinon_1 = __importDefault(require("sinon"));
+const express_1 = __importDefault(require("express"));
+const typedi_1 = require("typedi");
+const loopbackRequest_1 = __importDefault(require("../helpers/loopbackRequest"));
+const apikeys_1 = require("../../src/app/routers/apikeys");
+const ApiKeyService_1 = require("../../src/services/ApiKeyService");
+/**
+ * POST /apikeys stores the scopes it is given. It stored any string, so a
+ * typo (`session`, `Admin`) made a key that silently had none of the scopes
+ * its maker meant, and a list shown back on the API keys page that no check
+ * reads. It takes the four scopes POST /profile/tokens takes.
+ */
+describe('POST /apikeys takes only scopes that exist', () => {
+    let create;
+    function app(auth = {}) {
+        const a = (0, express_1.default)();
+        a.use(express_1.default.json());
+        a.use((req, _res, next) => {
+            req.auth = Object.assign({ kind: 'user-session', userId: 'admin1', role: 'SUPER_ADMIN', scopes: 'admin,devices,sessions,read' }, auth);
+            next();
+        });
+        a.use('/apikeys', (0, apikeys_1.apiKeysRouter)());
+        return a;
+    }
+    beforeEach(() => {
+        create = sinon_1.default.stub(typedi_1.Container.get(ApiKeyService_1.ApiKeyService), 'create').resolves({ id: 'k1', raw: 'raw' });
+    });
+    afterEach(() => sinon_1.default.restore());
+    for (const scopes of [['root'], ['sessions', 'Admin'], ['session'], [42]]) {
+        it(`refuses ${JSON.stringify(scopes)}`, () => __awaiter(void 0, void 0, void 0, function* () {
+            const r = yield (0, loopbackRequest_1.default)(app()).post('/apikeys').send({ name: 'CI', scopes });
+            (0, chai_1.expect)(r.status).to.equal(400);
+            (0, chai_1.expect)(r.body.error).to.equal('scopes must be some of read, sessions, devices, admin');
+            (0, chai_1.expect)(create.called).to.equal(false);
+        }));
+    }
+    it('creates a key with known scopes', () => __awaiter(void 0, void 0, void 0, function* () {
+        const r = yield (0, loopbackRequest_1.default)(app())
+            .post('/apikeys')
+            .send({ name: 'CI', scopes: ['sessions', 'devices'] });
+        (0, chai_1.expect)(r.status).to.equal(200);
+        (0, chai_1.expect)(create.firstCall.args[0].scopes).to.deep.equal(['sessions', 'devices']);
+    }));
+    // Made with a credential that expires, a key ends no later than it: an
+    // admin's 1-hour Bearer token made itself a key that never expired.
+    describe('from a credential that expires', () => {
+        const inAnHour = new Date(Date.now() + 3600000);
+        const bearer = () => app({ kind: 'bearer', scopes: 'admin', credentialExpiresAt: inAnHour.getTime() });
+        it('expires with that credential when no expiresAt is asked for', () => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            const r = yield (0, loopbackRequest_1.default)(bearer())
+                .post('/apikeys')
+                .send({ name: 'CI', scopes: ['sessions'] });
+            (0, chai_1.expect)(r.status).to.equal(200);
+            (0, chai_1.expect)(r.body.expiresAt).to.equal(inAnHour.toISOString());
+            (0, chai_1.expect)((_a = create.firstCall.args[0].expiresAt) === null || _a === void 0 ? void 0 : _a.getTime()).to.equal(inAnHour.getTime());
+        }));
+        it('refuses an expiresAt later than that credential', () => __awaiter(void 0, void 0, void 0, function* () {
+            const later = new Date(inAnHour.getTime() + 60000).toISOString();
+            const r = yield (0, loopbackRequest_1.default)(bearer())
+                .post('/apikeys')
+                .send({ name: 'CI', scopes: ['sessions'], expiresAt: later });
+            (0, chai_1.expect)(r.status).to.equal(400);
+            (0, chai_1.expect)(r.body.error).to.match(/later than the credential/);
+            (0, chai_1.expect)(create.called).to.equal(false);
+        }));
+    });
+});

package/lib/test/unit/apple-family.spec.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const appleFamily_1 = require("../../src/data-service/appleFamily");
+/**
+ * Whether a phone is an iPhone or an iPad, for `appium:iPhoneOnly` and
+ * `appium:iPadOnly`. Its model and form factor are read before its name: a
+ * real phone is named by its owner.
+ */
+describe('appleFamilyOf', () => {
+    const ios = (over) => (Object.assign({ platform: 'ios', name: 'unknown' }, over));
+    it('reads the family from the model first', () => {
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ model: 'iPhone17,3', name: 'My iPad' }))).to.equal('iphone');
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ model: 'iPad13,4', name: 'iPhone spare' }))).to.equal('ipad');
+    });
+    it('reads it from the form factor when there is no model (a simulator)', () => {
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ formFactor: 'phone', name: 'Test device 1' }))).to.equal('iphone');
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ formFactor: 'tablet', name: 'Test device 2' }))).to.equal('ipad');
+    });
+    it('puts an Apple TV in neither family', () => {
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ formFactor: 'tv', name: 'iPad-like TV' }))).to.equal(undefined);
+    });
+    it('falls back to the marketing name, then the name, for an old row', () => {
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ marketingName: 'iPad Air (5th generation)', name: 'x' }))).to.equal('ipad');
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ name: 'iPhone 13' }))).to.equal('iphone');
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ name: 'iPad (9th generation)' }))).to.equal('ipad');
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ name: 'unknown' }))).to.equal(undefined);
+    });
+    it('is case-insensitive about a name', () => {
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)(ios({ name: 'IPHONE 12' }))).to.equal('iphone');
+    });
+    it('is nothing for a device that is not iOS', () => {
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)({ platform: 'android', name: 'Pixel Tablet', formFactor: 'tablet' })).to.equal(undefined);
+        (0, chai_1.expect)((0, appleFamily_1.appleFamilyOf)({ platform: 'android', name: 'iPhone clone', model: 'iPhone1,1' })).to.equal(undefined);
+    });
+});

package/lib/test/unit/authMiddleware.bearer.spec.js

@@ -65,6 +65,15 @@ describe('authMiddleware — Bearer branch', () => {
         (0, chai_1.expect)(req.auth.userId).to.equal('u1');
         (0, chai_1.expect)(req.auth.scopes).to.equal('devices,read');
     }));
+    it("drops admin from a demoted user's token: req.auth.scopes follows the role now", () => __awaiter(void 0, void 0, void 0, function* () {
+        // `user` is a MEMBER: the token was minted while they were an admin.
+        const token = yield keySvc.sign({ sub: 'u1', scopes: 'admin,devices,sessions,read' }, { audience: 'xenon-rest', ttlSeconds: 60 });
+        const req = { headers: { authorization: `Bearer ${token}` }, query: {} };
+        const next = sinon_1.default.spy();
+        yield (0, authMiddleware_1.authMiddleware)(req, fakeRes(), next);
+        (0, chai_1.expect)(next.calledOnce).to.equal(true);
+        (0, chai_1.expect)(req.auth.scopes).to.equal('devices,sessions,read');
+    }));
     // Widened by Phase 2a Task 1: the MCP plugin's tools call this same REST
     // surface with a gateway-injected xenon-mcp-audience token, so it must be
     // accepted here too (see authMiddleware.mcpAudience.spec.ts for the full