@xenon-device-management/xenon 2.0.0 → 2.2.0

package/lib/test/unit/session-upgrade-guard.spec.js

@@ -0,0 +1,571 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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 });
+const chai_1 = require("chai");
+const http_1 = __importDefault(require("http"));
+const net_1 = __importDefault(require("net"));
+const path_1 = __importDefault(require("path"));
+const sinon_1 = __importDefault(require("sinon"));
+const ws_1 = __importStar(require("ws"));
+const commandCaller_1 = require("../../src/middleware/commandCaller");
+const sessionUpgradeGuard_1 = require("../../src/middleware/sessionUpgradeGuard");
+const registerCommandAuth_1 = require("../../src/app/registerCommandAuth");
+/**
+ * Session WebSockets under XENON_REQUIRE_COMMAND_AUTH.
+ *
+ * WebDriver BiDi (`<basePath>/bidi/<sessionId>`) and the endpoints drivers
+ * register (`/ws/session/<sessionId>/...`) are WebSocket upgrades, which never
+ * pass through the Express routes the per-command check guards. Without the
+ * guard, anyone with a session id can attach.
+ *
+ * Appium dispatches upgrades one of two ways (base-driver `server()`):
+ * - Node >= 22.21 / 24.9 (`shouldUpgradeCallback`): an `upgrade` listener on the
+ *   http.Server, added before any plugin's updateServer runs.
+ * - older Node: an Express middleware (`handleUpgrade`), reached only while the
+ *   server has no `upgrade` listener at all.
+ * These tests use Appium's own dispatch functions for both, on a real
+ * http.Server with a real WebSocket client.
+ */
+function appiumDir() {
+    return path_1.default.dirname(require.resolve('appium/package.json'));
+}
+function appiumExpress() {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require(require.resolve('express', { paths: [appiumDir()] }));
+}
+/** base-driver's upgrade dispatch: tryHandleWebSocketUpgrade and handleUpgrade. */
+function appiumUpgradeDispatch() {
+    const baseDriverDir = path_1.default.dirname(require.resolve('@appium/base-driver/package.json', { paths: [appiumDir()] }));
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require(path_1.default.join(baseDriverDir, 'build/lib/express/middleware'));
+}
+const USERS = {
+    alice: { id: 'alice', role: 'MEMBER', status: 'ACTIVE' },
+    bob: { id: 'bob', role: 'MEMBER', status: 'ACTIVE' },
+    carol: { id: 'carol', role: 'ADMIN', status: 'ACTIVE' },
+    root: { id: 'root', role: 'SUPER_ADMIN', status: 'ACTIVE' },
+};
+const KEYS = {
+    'alice-token': ['alice', 'devices,sessions,read'],
+    'bob-token': ['bob', 'devices,sessions,read'],
+    'carol-ordinary': ['carol', 'devices,sessions,read'],
+    'carol-admin': ['carol', 'admin,devices,sessions,read'],
+};
+const JWTS = {
+    'alice-jwt': ['alice', 'devices,sessions,read'],
+    'root-jwt': ['root', 'sessions'],
+};
+const OWNERS = {
+    's-alice': 'alice',
+    's-bob': 'bob',
+    's-anon': null,
+};
+const as = (token) => ({
+    'x-xenon-access-key': `ak-${KEYS[token][0]}`,
+    'x-xenon-token': token,
+});
+const bearer = (jwt) => ({ authorization: `Bearer ${jwt}` });
+/** Open a WebSocket and report how the server answered the upgrade. */
+function connect(port, urlPath, headers = {}) {
+    return new Promise((resolve) => {
+        const ws = new ws_1.default(`ws://127.0.0.1:${port}${urlPath}`, { headers });
+        ws.on('open', () => {
+            resolve({ kind: 'open' });
+            ws.terminate();
+        });
+        ws.on('unexpected-response', (req, res) => {
+            var _a;
+            resolve({ kind: 'http', status: (_a = res.statusCode) !== null && _a !== void 0 ? _a : 0 });
+            req.destroy();
+        });
+        ws.on('error', (err) => resolve({ kind: 'error', message: err.message }));
+    });
+}
+/** Send a raw upgrade request and collect everything until the server closes. */
+function rawUpgrade(port, urlPath) {
+    return new Promise((resolve, reject) => {
+        const socket = net_1.default.connect(port, '127.0.0.1', () => {
+            socket.write(`GET ${urlPath} HTTP/1.1\r\nHost: 127.0.0.1\r\nUpgrade: websocket\r\n` +
+                'Connection: Upgrade\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n' +
+                'Sec-WebSocket-Version: 13\r\n\r\n');
+        });
+        let data = '';
+        socket.on('data', (chunk) => (data += chunk.toString('latin1')));
+        socket.on('close', () => resolve(data));
+        socket.on('error', reject);
+        socket.setTimeout(5000, () => reject(new Error(`no close after: ${JSON.stringify(data)}`)));
+    });
+}
+const tick = (ms = 20) => new Promise((resolve) => setTimeout(resolve, ms));
+const openSockets = new WeakMap();
+/** Listen on 127.0.0.1, remembering every connection so shut() can end it. */
+function listen(server) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const sockets = new Set();
+        openSockets.set(server, sockets);
+        server.on('connection', (socket) => {
+            sockets.add(socket);
+            socket.on('close', () => sockets.delete(socket));
+        });
+        yield new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+        return server.address().port;
+    });
+}
+/**
+ * Close the server and every connection. An upgraded socket leaves the HTTP
+ * server's own bookkeeping (closeAllConnections misses it), and one that no
+ * listener reads never sees the client's FIN, so it is destroyed here.
+ */
+function shut(server) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if (!server)
+            return;
+        for (const socket of (_a = openSockets.get(server)) !== null && _a !== void 0 ? _a : [])
+            socket.destroy();
+        server.closeAllConnections();
+        yield new Promise((resolve) => server.close(() => resolve()));
+    });
+}
+describe('session WebSockets under per-command auth', () => {
+    describe('which upgrades belong to a session', () => {
+        const cases = [
+            // WebDriver BiDi, as Appium's main registers it under the base path.
+            ['/wd/hub/bidi/abc', '/wd/hub', ['abc']],
+            ['/wd/hub/bidi/abc/', '/wd/hub', ['abc']],
+            ['/WD/HUB/BIDI/abc', '/wd/hub', ['abc']],
+            ['/wd/hub/x/../bidi/abc', '/wd/hub', ['abc']],
+            ['/wd/hub/bidi/%2e%2e/bidi/abc', '/wd/hub', ['abc']],
+            ['http://elsewhere/wd/hub/bidi/abc', '/wd/hub', ['abc']],
+            // Appium reads the bidi session id from the raw URL, query and all; both count.
+            ['/wd/hub/bidi/abc?x=1', '/wd/hub', ['abc', 'abc?x=1']],
+            ['/wd/hub/bidi/ab%2Fc', '/wd/hub', ['ab%2Fc', 'ab/c']],
+            ['/bidi/abc', '', ['abc']],
+            // The umbrella bidi socket belongs to no session.
+            ['/wd/hub/bidi', '/wd/hub', []],
+            ['/wd/hub/bidi/', '/wd/hub', []],
+            // Outside the base path Appium routes nothing to bidi.
+            ['/bidi/abc', '/wd/hub', []],
+            // Driver endpoints (base-driver's DEFAULT_WS_PATHNAME_PREFIX), with or without the base path.
+            ['/ws/session/abc/appium/device/logcat', '/wd/hub', ['abc']],
+            ['/wd/hub/ws/session/abc/appium/device/syslog', '/wd/hub', ['abc']],
+            ['/WS/SESSION/abc/appium/device/logcat/', '/wd/hub', ['abc']],
+            ['/ws/session/abc', '', ['abc']],
+            // Not session WebSockets.
+            ['/xenon/api/control/udid-1/logcat?ticket=t', '/wd/hub', []],
+            ['/xenon/api/control/udid-1/stream/h264?ticket=t', '/wd/hub', []],
+            ['/socket.io/?EIO=4&transport=websocket', '/wd/hub', []],
+            ['/wd/hub/session/abc/url', '/wd/hub', []],
+            ['/ws/other/abc', '/wd/hub', []],
+        ];
+        for (const [url, basePath, ids] of cases) {
+            it(`${url} (base path ${JSON.stringify(basePath)}) -> ${JSON.stringify(ids)}`, () => {
+                (0, chai_1.expect)((0, sessionUpgradeGuard_1.sessionIdsOfUpgrade)(url, basePath)).to.deep.equal(ids);
+            });
+        }
+        it("normalises the base path the way Appium does ('wd/hub/' -> '/wd/hub')", () => {
+            (0, chai_1.expect)((0, sessionUpgradeGuard_1.sessionIdsOfUpgrade)('/wd/hub/bidi/abc', 'wd/hub/')).to.deep.equal(['abc']);
+            (0, chai_1.expect)((0, sessionUpgradeGuard_1.sessionIdsOfUpgrade)('/wd/hub/bidi/abc', undefined)).to.deep.equal([]);
+        });
+    });
+    describe('registration', () => {
+        const quiet = (errors) => ({
+            info: () => undefined,
+            warn: () => undefined,
+            error: (m) => errors.push(m),
+        });
+        it('refuses to start when the setting is on and there is no HTTP server to guard', () => {
+            const errors = [];
+            (0, chai_1.expect)(() => (0, registerCommandAuth_1.registerSessionUpgradeGuard)(undefined, appiumExpress()(), { basePath: '/wd/hub' }, {
+                enabled: () => true,
+                authDisabled: () => false,
+                logger: quiet(errors),
+            })).to.throw(/XENON_REQUIRE_COMMAND_AUTH/);
+            (0, chai_1.expect)(errors).to.have.length(1);
+        });
+        it('refuses to start when the setting is on and the Express guard cannot be placed', () => {
+            const errors = [];
+            (0, chai_1.expect)(() => (0, registerCommandAuth_1.registerSessionUpgradeGuard)(http_1.default.createServer(), { use: () => undefined }, { basePath: '/wd/hub' }, { enabled: () => true, authDisabled: () => false, logger: quiet(errors) })).to.throw(/XENON_REQUIRE_COMMAND_AUTH/);
+        });
+        it('logs an error but starts when the setting is off', () => {
+            const errors = [];
+            const result = (0, registerCommandAuth_1.registerSessionUpgradeGuard)(undefined, appiumExpress()(), {}, {
+                enabled: () => false,
+                authDisabled: () => false,
+                logger: quiet(errors),
+            });
+            (0, chai_1.expect)(result.placed).to.equal(false);
+            (0, chai_1.expect)(errors).to.have.length(1);
+        });
+    });
+    // 'listener': Appium on Node >= 22.21 / 24.9, its upgrade listener added before plugins.
+    // 'express': Appium on older Node, its Express upgrade middleware, no upgrade listener.
+    for (const mode of ['listener', 'express']) {
+        describe(`Appium dispatching upgrades with its ${mode}`, () => {
+            let enabled;
+            let authDisabled;
+            let ownerOf;
+            let verifyKeyPair;
+            let verifyBearer;
+            let warnings;
+            let errors;
+            let server;
+            let port;
+            /** URLs Appium's WebSocket servers accepted. */
+            let accepted;
+            /** Calls into Appium's WebSocket servers' handleUpgrade, accepted or not. */
+            let appiumHandled;
+            beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+                enabled = true;
+                authDisabled = false;
+                warnings = [];
+                errors = [];
+                accepted = [];
+                verifyKeyPair = sinon_1.default.stub().callsFake((accessKey, token) => __awaiter(void 0, void 0, void 0, function* () {
+                    const key = KEYS[token];
+                    if (!key || accessKey !== `ak-${key[0]}`)
+                        return null;
+                    return {
+                        row: { id: `key-${token}`, userId: key[0], scopes: key[1], expiresAt: null },
+                        user: USERS[key[0]],
+                    };
+                }));
+                verifyBearer = sinon_1.default.stub().callsFake((jwt) => __awaiter(void 0, void 0, void 0, function* () {
+                    const t = JWTS[jwt];
+                    if (!t)
+                        return null;
+                    return { payload: { sub: t[0], scopes: t[1] }, user: USERS[t[0]] };
+                }));
+                ownerOf = sinon_1.default.stub().callsFake((id) => __awaiter(void 0, void 0, void 0, function* () { return (id in OWNERS ? OWNERS[id] : null); }));
+                const dispatch = appiumUpgradeDispatch();
+                const bidi = new ws_1.WebSocketServer({ noServer: true });
+                const driverLogcat = new ws_1.WebSocketServer({ noServer: true });
+                for (const wss of [bidi, driverLogcat]) {
+                    wss.on('connection', (ws, req) => {
+                        accepted.push(String(req.url));
+                        ws.on('error', () => undefined);
+                    });
+                }
+                appiumHandled = [
+                    sinon_1.default.spy(bidi, 'handleUpgrade'),
+                    sinon_1.default.spy(driverLogcat, 'handleUpgrade'),
+                ];
+                // What Appium's main and a driver register.
+                const mapping = {
+                    '/wd/hub/bidi': bidi,
+                    '/wd/hub/bidi/:sessionId': bidi,
+                    '/ws/session/s-alice/appium/device/logcat': driverLogcat,
+                };
+                const app = appiumExpress()();
+                if (mode === 'express')
+                    app.use(dispatch.handleUpgrade(mapping));
+                app.use((_req, res) => res.status(404).json({ value: null }));
+                const httpServer = http_1.default.createServer(app);
+                if (mode === 'listener') {
+                    // Appium's configureHttp, verbatim in effect.
+                    httpServer.on('upgrade', (req, socket, head) => {
+                        if (!dispatch.tryHandleWebSocketUpgrade(req, socket, head, mapping))
+                            socket.destroy();
+                    });
+                }
+                const result = (0, registerCommandAuth_1.registerSessionUpgradeGuard)(httpServer, app, { basePath: 'wd/hub/' }, {
+                    enabled: () => enabled,
+                    authDisabled: () => authDisabled,
+                    verifier: new commandCaller_1.CommandCallerVerifier({ verifyKeyPair, verifyBearer }),
+                    ownerOf,
+                    logger: {
+                        info: () => undefined,
+                        warn: (m) => warnings.push(m),
+                        error: (m) => errors.push(m),
+                    },
+                });
+                (0, chai_1.expect)(result.placed).to.equal(true);
+                server = httpServer;
+                port = yield listen(httpServer);
+            }));
+            afterEach(() => __awaiter(void 0, void 0, void 0, function* () {
+                const s = server;
+                server = undefined;
+                yield shut(s);
+            }));
+            const appiumSawAnything = () => appiumHandled.some((spy) => spy.called);
+            describe('who may attach', () => {
+                it("refuses a session upgrade without credentials with 404, before Appium's handler runs", () => __awaiter(void 0, void 0, void 0, function* () {
+                    (0, chai_1.expect)(yield connect(port, '/wd/hub/bidi/s-alice')).to.deep.equal({
+                        kind: 'http',
+                        status: 404,
+                    });
+                    (0, chai_1.expect)(appiumSawAnything()).to.equal(false);
+                    (0, chai_1.expect)(accepted).to.deep.equal([]);
+                    (0, chai_1.expect)(verifyKeyPair.called || verifyBearer.called || ownerOf.called).to.equal(false);
+                    (0, chai_1.expect)(warnings).to.have.length(1);
+                    (0, chai_1.expect)(warnings[0]).to.include('s-alice');
+                    (0, chai_1.expect)(warnings[0]).to.include('no credentials');
+                }));
+                it('answers the refusal with an HTTP 404 on the raw socket, then closes it', () => __awaiter(void 0, void 0, void 0, function* () {
+                    const reply = yield rawUpgrade(port, '/wd/hub/bidi/s-alice');
+                    (0, chai_1.expect)(reply).to.match(/^HTTP\/1\.1 404 Not Found\r\n/);
+                    (0, chai_1.expect)(reply).not.to.include('101');
+                    (0, chai_1.expect)(appiumSawAnything()).to.equal(false);
+                }));
+                it("lets the owner through to Appium's handler", () => __awaiter(void 0, void 0, void 0, function* () {
+                    (0, chai_1.expect)(yield connect(port, '/wd/hub/bidi/s-alice', as('alice-token'))).to.deep.equal({
+                        kind: 'open',
+                    });
+                    (0, chai_1.expect)(accepted).to.deep.equal(['/wd/hub/bidi/s-alice']);
+                    (0, chai_1.expect)(warnings).to.deep.equal([]);
+                }));
+                it("lets the owner's Bearer token through", () => __awaiter(void 0, void 0, void 0, function* () {
+                    (0, chai_1.expect)((yield connect(port, '/wd/hub/bidi/s-alice', bearer('alice-jwt'))).kind).to.equal('open');
+                }));
+                it('lets an override admin attach to a session they do not own', () => __awaiter(void 0, void 0, void 0, function* () {
+                    (0, chai_1.expect)((yield connect(port, '/wd/hub/bidi/s-alice', as('carol-admin'))).kind).to.equal('open');
+                    (0, chai_1.expect)((yield connect(port, '/wd/hub/bidi/s-anon', bearer('root-jwt'))).kind).to.equal('open');
+                }));
+                it("refuses another user, and an ADMIN's ordinary key, with 404", () => __awaiter(void 0, void 0, void 0, function* () {
+                    for (const who of ['bob-token', 'carol-ordinary']) {
+                        (0, chai_1.expect)(yield connect(port, '/wd/hub/bidi/s-alice', as(who)), who).to.deep.equal({
+                            kind: 'http',
+                            status: 404,
+                        });
+                    }
+                    (0, chai_1.expect)(appiumSawAnything()).to.equal(false);
+                    (0, chai_1.expect)(warnings.join('\n')).not.to.include('bob-token');
+                }));
+                it('refuses everyone but override admins on a session nobody owns', () => __awaiter(void 0, void 0, void 0, function* () {
+                    (0, chai_1.expect)(yield connect(port, '/wd/hub/bidi/s-anon', as('alice-token'))).to.deep.equal({
+                        kind: 'http',
+                        status: 404,
+                    });
+                }));
+                it('refuses credentials that do not verify', () => __awaiter(void 0, void 0, void 0, function* () {
+                    const res = yield connect(port, '/wd/hub/bidi/s-alice', {
+                        'x-xenon-access-key': 'ak-alice',
+                        'x-xenon-token': 'guessed',
+                    });
+                    (0, chai_1.expect)(res).to.deep.equal({ kind: 'http', status: 404 });
+                    (0, chai_1.expect)(ownerOf.called).to.equal(false);
+                }));
+                it("guards a driver's /ws/session/<id>/... endpoint the same way", () => __awaiter(void 0, void 0, void 0, function* () {
+                    const url = '/ws/session/s-alice/appium/device/logcat';
+                    (0, chai_1.expect)(yield connect(port, url, as('bob-token'))).to.deep.equal({
+                        kind: 'http',
+                        status: 404,
+                    });
+                    (0, chai_1.expect)(appiumSawAnything()).to.equal(false);
+                    (0, chai_1.expect)((yield connect(port, url, as('alice-token'))).kind).to.equal('open');
+                    (0, chai_1.expect)(accepted).to.deep.equal([url]);
+                }));
+                it('answers a session the caller may not use exactly as one that does not exist', () => __awaiter(void 0, void 0, void 0, function* () {
+                    const refused = yield rawUpgrade(port, '/wd/hub/bidi/s-alice');
+                    const missing = yield rawUpgrade(port, '/wd/hub/bidi/no-such-session');
+                    (0, chai_1.expect)(refused).to.equal(missing);
+                }));
+            });
+            describe('what it leaves alone', () => {
+                it('lets the umbrella /bidi socket, which belongs to no session, through untouched', () => __awaiter(void 0, void 0, void 0, function* () {
+                    (0, chai_1.expect)((yield connect(port, '/wd/hub/bidi')).kind).to.equal('open');
+                    (0, chai_1.expect)(verifyKeyPair.called || ownerOf.called).to.equal(false);
+                    (0, chai_1.expect)(warnings).to.deep.equal([]);
+                }));
+                it('does nothing at all when the setting is off (the default)', () => __awaiter(void 0, void 0, void 0, function* () {
+                    enabled = false;
+                    (0, chai_1.expect)((yield connect(port, '/wd/hub/bidi/s-alice')).kind).to.equal('open');
+                    (0, chai_1.expect)(verifyKeyPair.called || verifyBearer.called || ownerOf.called).to.equal(false);
+                    (0, chai_1.expect)(warnings.concat(errors)).to.deep.equal([]);
+                }));
+                it('does nothing when auth is disabled, even with the setting on', () => __awaiter(void 0, void 0, void 0, function* () {
+                    authDisabled = true;
+                    (0, chai_1.expect)((yield connect(port, '/wd/hub/bidi/s-alice')).kind).to.equal('open');
+                    (0, chai_1.expect)(ownerOf.called).to.equal(false);
+                }));
+                it('leaves ordinary HTTP requests to the same paths alone', () => __awaiter(void 0, void 0, void 0, function* () {
+                    const res = yield new Promise((resolve) => http_1.default.get(`http://127.0.0.1:${port}/wd/hub/bidi/s-alice`, (r) => {
+                        var _a;
+                        r.resume();
+                        resolve((_a = r.statusCode) !== null && _a !== void 0 ? _a : 0);
+                    }));
+                    (0, chai_1.expect)(res).to.equal(404);
+                    (0, chai_1.expect)(warnings).to.deep.equal([]);
+                    (0, chai_1.expect)(ownerOf.called).to.equal(false);
+                }));
+            });
+            describe('failing closed', () => {
+                it('answers 503 when the owner lookup fails, and never hands the socket on', () => __awaiter(void 0, void 0, void 0, function* () {
+                    ownerOf.rejects(new Error('database is locked\nSELECT secret'));
+                    (0, chai_1.expect)(yield connect(port, '/wd/hub/bidi/s-alice', as('alice-token'))).to.deep.equal({
+                        kind: 'http',
+                        status: 503,
+                    });
+                    (0, chai_1.expect)(appiumSawAnything()).to.equal(false);
+                    (0, chai_1.expect)(errors).to.have.length(1);
+                    (0, chai_1.expect)(errors[0]).to.include('database is locked');
+                    (0, chai_1.expect)(errors[0]).not.to.include('SELECT');
+                }));
+                it('answers 503 when the credential check fails', () => __awaiter(void 0, void 0, void 0, function* () {
+                    verifyKeyPair.rejects(new Error('database is locked'));
+                    (0, chai_1.expect)(yield connect(port, '/wd/hub/bidi/s-alice', as('alice-token'))).to.deep.equal({
+                        kind: 'http',
+                        status: 503,
+                    });
+                    (0, chai_1.expect)(appiumSawAnything()).to.equal(false);
+                }));
+                it("drops a client that leaves during the check without reaching Appium's handler or crashing", () => __awaiter(void 0, void 0, void 0, function* () {
+                    let release = () => undefined;
+                    ownerOf.callsFake(() => new Promise((resolve) => (release = resolve)));
+                    const socket = net_1.default.connect(port, '127.0.0.1');
+                    yield new Promise((resolve) => socket.on('connect', () => resolve()));
+                    socket.on('error', () => undefined);
+                    socket.write('GET /wd/hub/bidi/s-alice HTTP/1.1\r\nHost: x\r\nUpgrade: websocket\r\n' +
+                        'Connection: Upgrade\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n' +
+                        'Sec-WebSocket-Version: 13\r\nx-xenon-access-key: ak-alice\r\n' +
+                        'x-xenon-token: alice-token\r\n\r\n');
+                    yield tick(50);
+                    (0, chai_1.expect)(ownerOf.called, 'the check is under way').to.equal(true);
+                    // A reset, not a clean close: the server side sees ECONNRESET, which
+                    // would crash the process if nothing were listening for it.
+                    socket.resetAndDestroy();
+                    yield tick(50);
+                    release('alice');
+                    yield tick(50);
+                    (0, chai_1.expect)(appiumSawAnything()).to.equal(false);
+                    (0, chai_1.expect)(accepted).to.deep.equal([]);
+                }));
+            });
+        });
+    }
+    describe("next to Xenon's own upgrade listeners (Appium's Express middleware unreachable)", () => {
+        // What the lab ran on Node < 22.21 before the upgrade router: Appium's
+        // upgrade middleware plus Xenon's h264 and logcat listeners. With any
+        // `upgrade` listener present, Node never hands an upgrade to Express, so
+        // Appium's handler is not reached at all; the guard's job here is only to
+        // refuse. The router's own wiring is in upgrade-router.spec.ts and
+        // ws-upgrade-routing-appium-server.spec.ts.
+        let server;
+        let port;
+        let seenByListeners;
+        let xenonAccepted;
+        let ownerOf;
+        beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+            seenByListeners = [];
+            xenonAccepted = [];
+            ownerOf = sinon_1.default.stub().callsFake((id) => __awaiter(void 0, void 0, void 0, function* () { return (id in OWNERS ? OWNERS[id] : null); }));
+            const dispatch = appiumUpgradeDispatch();
+            const bidi = new ws_1.WebSocketServer({ noServer: true });
+            const app = appiumExpress()();
+            app.use(dispatch.handleUpgrade({ '/wd/hub/bidi/:sessionId': bidi }));
+            const httpServer = http_1.default.createServer(app);
+            (0, registerCommandAuth_1.registerSessionUpgradeGuard)(httpServer, app, { basePath: '/wd/hub' }, {
+                enabled: () => true,
+                authDisabled: () => false,
+                verifier: new commandCaller_1.CommandCallerVerifier({
+                    verifyKeyPair: sinon_1.default.stub().callsFake((_ak, token) => __awaiter(void 0, void 0, void 0, function* () {
+                        return KEYS[token]
+                            ? {
+                                row: {
+                                    id: 'k',
+                                    userId: KEYS[token][0],
+                                    scopes: KEYS[token][1],
+                                    expiresAt: null,
+                                },
+                                user: USERS[KEYS[token][0]],
+                            }
+                            : null;
+                    })),
+                    verifyBearer: sinon_1.default.stub().resolves(null),
+                }),
+                ownerOf,
+                logger: { info: () => undefined, warn: () => undefined, error: () => undefined },
+            });
+            // Xenon's attachLogcatWs / attachH264Ws shape: claim their own path, ignore the rest.
+            const xenonWss = new ws_1.WebSocketServer({ noServer: true });
+            httpServer.on('upgrade', (req, socket, head) => {
+                seenByListeners.push({ url: String(req.url), alive: !socket.destroyed });
+                if (!/^\/xenon\/api\/control\/[^/]+\/(logcat|stream\/h264)\?/.test(String(req.url)))
+                    return;
+                xenonWss.handleUpgrade(req, socket, head, (ws) => {
+                    xenonAccepted.push(String(req.url));
+                    ws.on('error', () => undefined);
+                });
+            });
+            server = httpServer;
+            port = yield listen(httpServer);
+        }));
+        afterEach(() => __awaiter(void 0, void 0, void 0, function* () {
+            const s = server;
+            server = undefined;
+            yield shut(s);
+        }));
+        it("leaves Xenon's ticketed WebSockets alone, with no credentials and no lookups", () => __awaiter(void 0, void 0, void 0, function* () {
+            for (const url of [
+                '/xenon/api/control/u1/logcat?ticket=t',
+                '/xenon/api/control/u1/stream/h264?ticket=t',
+            ]) {
+                (0, chai_1.expect)((yield connect(port, url)).kind, url).to.equal('open');
+            }
+            (0, chai_1.expect)(xenonAccepted).to.have.length(2);
+            (0, chai_1.expect)(ownerOf.called).to.equal(false);
+        }));
+        it('refuses a session upgrade with 404 before any listener sees it', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, chai_1.expect)(yield connect(port, '/wd/hub/bidi/s-alice', as('bob-token'))).to.deep.equal({
+                kind: 'http',
+                status: 404,
+            });
+            (0, chai_1.expect)(seenByListeners).to.deep.equal([]);
+        }));
+        it("hands the owner's upgrade on to the listeners, exactly as without the guard", () => __awaiter(void 0, void 0, void 0, function* () {
+            const ws = new ws_1.default(`ws://127.0.0.1:${port}/wd/hub/bidi/s-alice`, {
+                headers: as('alice-token'),
+            });
+            ws.on('error', () => undefined);
+            for (let i = 0; i < 50 && seenByListeners.length === 0; i++)
+                yield tick(10);
+            ws.terminate();
+            (0, chai_1.expect)(seenByListeners).to.deep.equal([{ url: '/wd/hub/bidi/s-alice', alive: true }]);
+        }));
+    });
+});

package/lib/test/unit/shutdown-drain-remote.spec.js

@@ -0,0 +1,58 @@
+"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 ShutdownCoordinator_1 = require("../../src/services/ShutdownCoordinator");
+const SessionLifecycleService_1 = require("../../src/services/SessionLifecycleService");
+const SessionManager_1 = require("../../src/sessions/SessionManager");
+const SessionType_1 = __importDefault(require("../../src/enums/SessionType"));
+/**
+ * A hub's graceful shutdown drains the sessions it knows. Its own (local)
+ * sessions die with the process, so they are finalized: video archived, the
+ * phone released, the row closed. A node's or a cloud provider's session keeps
+ * running there, and the restarted hub routes it again from its database. The
+ * drain used to finalize those too: the hub released the phone and closed the
+ * row, recovery then found nothing to route, and the node kept a session no
+ * client could reach, holding its phone until the idle timeout.
+ */
+describe('ShutdownCoordinator.drain', () => {
+    let stop;
+    const session = (id, type) => ({ getId: () => id, getType: () => type });
+    beforeEach(() => {
+        stop = sinon_1.default.stub(SessionLifecycleService_1.SessionLifecycleService.prototype, 'stopSessionForShutdown').resolves();
+    });
+    afterEach(() => sinon_1.default.restore());
+    it("finalizes this server's own sessions and leaves the ones other servers run", () => __awaiter(void 0, void 0, void 0, function* () {
+        sinon_1.default
+            .stub(SessionManager_1.SESSION_MANAGER, 'getAllSessions')
+            .returns([
+            session('local-1', SessionType_1.default.LOCAL),
+            session('remote-1', SessionType_1.default.REMOTE),
+            session('cloud-1', SessionType_1.default.CLOUD),
+        ]);
+        const result = yield new ShutdownCoordinator_1.ShutdownCoordinator().drain(1000, 500);
+        (0, chai_1.expect)(stop.args.map((args) => args[0])).to.deep.equal(['local-1']);
+        (0, chai_1.expect)(result).to.deep.equal({ attempted: 1, completed: 1 });
+    }));
+    it('drains nothing on a hub whose only sessions run on nodes', () => __awaiter(void 0, void 0, void 0, function* () {
+        sinon_1.default
+            .stub(SessionManager_1.SESSION_MANAGER, 'getAllSessions')
+            .returns([session('remote-1', SessionType_1.default.REMOTE)]);
+        const result = yield new ShutdownCoordinator_1.ShutdownCoordinator().drain(1000, 500);
+        (0, chai_1.expect)(stop.called).to.equal(false);
+        (0, chai_1.expect)(result).to.deep.equal({ attempted: 0, completed: 0 });
+    }));
+});

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

@@ -41,7 +41,9 @@ describe('SocketServer — authenticate() bearer path', () => {
     let keySvc;
     let server;
     let authenticate;
+    let restoreContainer;
     beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+        restoreContainer = (0, container_registration_1.saveRegistrations)(JwtKeyService_1.JwtKeyService, ApiKeyService_1.ApiKeyService);
         dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'xenon-socket-bearer-'));
         keySvc = new JwtKeyService_1.JwtKeyService();
         yield keySvc.init(dir);
@@ -55,7 +57,7 @@ describe('SocketServer — authenticate() bearer path', () => {
     }));
     afterEach(() => {
         sinon_1.default.restore();
-        typedi_1.Container.reset();
+        restoreContainer();
         fs_1.default.rmSync(dir, { recursive: true, force: true });
     });
     it('1. valid xenon-rest bearer JWT for an ACTIVE user → principal dashboard', () => __awaiter(void 0, void 0, void 0, function* () {