@xenon-device-management/xenon 2.0.0 → 2.2.0

package/lib/src/generated/client/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "prisma-client-d6a27094f142fa4c61402cd0048ae9081cb125a1a6a065e48a3b1066db77d5b1",
+  "name": "prisma-client-2fecbe6024329bf05b69cdf448f1b687e32645450beda6a210a882d44a7ffb8d",
   "main": "index.js",
   "types": "index.d.ts",
   "browser": "index-browser.js",

package/lib/src/generated/client/schema.prisma

@@ -196,10 +196,19 @@ model Device {
   lockedAt                     Float?   @map("locked_at")
   teamId                       String?
   team                         Team?    @relation(fields: [teamId], references: [id])
+  // This server's claim on the phone for a session: when it was taken, and
+  // the session's id once the session exists (null while it is created).
+  // See src/data-service/deviceClaims.ts.
+  claimSessionId               String?
+  claimedAt                    Float?
+  // On a hub, what the phone's node last reported: busy there. `busy` is the
+  // claim OR this. Always false for a phone this server drives.
+  nodeBusy                     Boolean? @default(false)
 
   @@id([udid, host])
   @@index([owningSessionId])
   @@index([teamId])
+  @@index([claimSessionId])
 }
 
 model PendingSession {

package/lib/src/generated/client/wasm.js

@@ -282,7 +282,10 @@ exports.Prisma.DeviceScalarFieldEnum = {
   cpuArchitecture: 'cpuArchitecture',
   owningSessionId: 'owningSessionId',
   lockedAt: 'lockedAt',
-  teamId: 'teamId'
+  teamId: 'teamId',
+  claimSessionId: 'claimSessionId',
+  claimedAt: 'claimedAt',
+  nodeBusy: 'nodeBusy'
 };
 
 exports.Prisma.PendingSessionScalarFieldEnum = {

package/lib/src/helpers/index.js

@@ -180,7 +180,11 @@ function isXenonRunning(host, tlsRejectUnauthorized) {
     return __awaiter(this, void 0, void 0, function* () {
         try {
             const client = InternalHttpClient_1.InternalHttpClient.getClient(tlsRejectUnauthorized);
-            yield client.get(`${host}/xenon/api/status`);
+            // /health is the one /xenon/api route with no login. The hub probes its
+            // nodes, and a node its hub, without credentials, so a login-only route
+            // (/status) called a server with auth on dead: the hub pruned its node's
+            // phones, and the node never registered with its hub.
+            yield client.get(`${host}/xenon/api/health`);
             return true;
         }
         catch (error) {

package/lib/src/logger.js

@@ -42,6 +42,11 @@ const SENSITIVE_KEY_PATTERNS = [
     // 'token' already matches it; named so it survives any narrowing of that
     // pattern. A lease token gives its holder the lease's device.
     'leasetoken',
+    // accessKey, access_key and the x-xenon-access-key header (underscores
+    // and hyphens are stripped before matching). Half of a credential pair: it
+    // names the key a leaked token would complete. RequestLogService already
+    // hides it through its own 'key' pattern.
+    'accesskey',
 ];
 const REDACTED = '***REDACTED***';
 function isSensitiveKey(key) {

package/lib/src/middleware/authMiddleware.js

@@ -20,6 +20,9 @@ const AppDownloadTicketService_1 = require("../services/token/AppDownloadTicketS
 const config_1 = require("../config");
 const callerTeamIds_1 = require("../services/device-access/callerTeamIds");
 const verifyCredential_1 = require("./verifyCredential");
+const PluginContext_1 = require("../PluginContext");
+const hubSessionToken_1 = require("../gateway/hubSessionToken");
+const localDeviceHosts_1 = require("../device-managers/localDeviceHosts");
 const SESSION_COOKIE = 'xenon_dashboard_session';
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
 // Role → scopes derivation. The same table is used in profile token creation
@@ -64,6 +67,70 @@ function readCookie(req, name) {
     }
     return undefined;
 }
+/** One verifier per hub URL, so its fetched key set is reused. */
+const hubVerifiers = new Map();
+function hubVerifierFor(hub) {
+    let verifier = hubVerifiers.get(hub);
+    if (!verifier) {
+        verifier = new hubSessionToken_1.HubSessionTokenVerifier(hub);
+        hubVerifiers.set(hub, verifier);
+    }
+    return verifier;
+}
+/**
+ * On a node: the caller a hub's signed device-control call names, for
+ * `/control/<udid>/...` on the phone the token names, of this node. The hub
+ * checked the caller, the team rule and ownership before forwarding; the
+ * node's own ownership guard then judges that user again. undefined when the
+ * request isn't one (no hub token, not a node, not /control): the other
+ * credential paths decide it. 'refused' for a token that isn't a valid grant
+ * for this phone of this node; 'unavailable' when the hub's keys can't be
+ * fetched.
+ */
+function hubControlCallerOf(req) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const presented = req.headers[hubSessionToken_1.HUB_TOKEN_HEADER];
+        if (typeof presented !== 'string')
+            return undefined;
+        const context = typedi_1.Container.get(PluginContext_1.PluginContext);
+        const hub = (_a = context.pluginArgs) === null || _a === void 0 ? void 0 : _a.hub;
+        if (hub === undefined)
+            return undefined;
+        const match = /^\/control\/([^/]+)(?:\/|$)/.exec(req.path);
+        if (!match)
+            return undefined;
+        let udid;
+        try {
+            udid = decodeURIComponent(match[1]);
+        }
+        catch (_b) {
+            return 'refused';
+        }
+        let grant;
+        try {
+            grant = yield hubVerifierFor(hub).verifyControl(presented);
+        }
+        catch (err) {
+            return err instanceof hubSessionToken_1.HubTokenUnavailableError ? 'unavailable' : 'refused';
+        }
+        if (!grant || grant.udid !== udid)
+            return 'refused';
+        if (!(0, localDeviceHosts_1.isLocalDeviceHost)((0, localDeviceHosts_1.localDeviceHosts)(context.pluginArgs, context.port), grant.host)) {
+            return 'refused';
+        }
+        const role = grant.isAdmin ? 'ADMIN' : 'MEMBER';
+        return {
+            kind: 'hub-control',
+            userId: grant.userId,
+            role,
+            scopes: scopesForRole(role),
+            rateLimit: 300,
+            // The hub applied the team rule: the node's rows carry the hub's teams.
+            teamIds: undefined,
+        };
+    });
+}
 function authMiddleware(req, res, next) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d, _e, _f, _g, _h;
@@ -79,6 +146,19 @@ function authMiddleware(req, res, next) {
             req.apiKey = { id: 'auth-disabled', scopes: 'admin', rateLimit: 100000 };
             return next();
         }
+        // Path 0: on a node, the hub's signed device-control call
+        // (x-xenon-hub-token, audience xenon-node-control), for /control on the
+        // phone it names only. Anywhere else the header is not a credential.
+        const hubControl = yield hubControlCallerOf(req);
+        if (hubControl === 'refused')
+            return res.status(401).json({ error: 'invalid hub token' });
+        if (hubControl === 'unavailable') {
+            return res.status(503).json({ error: "the hub's token could not be checked" });
+        }
+        if (hubControl) {
+            req.auth = hubControl;
+            return next();
+        }
         const apiKeySvc = typedi_1.Container.get(ApiKeyService_1.ApiKeyService);
         const userSessionSvc = typedi_1.Container.get(UserSessionService_1.UserSessionService);
         const userSvc = typedi_1.Container.get(UserService_1.UserService);

package/lib/src/middleware/commandAuth.js

@@ -11,6 +11,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMMAND_AUTH_UNAVAILABLE_BODY = exports.COMMAND_AUTH_UNAVAILABLE_STATUS = exports.UNKNOWN_SESSION_BODY = exports.UNKNOWN_SESSION_STATUS = void 0;
 exports.commandAuthEnabled = commandAuthEnabled;
+exports.decideSessionAccess = decideSessionAccess;
+exports.summarize = summarize;
 exports.createCommandAuthMiddleware = createCommandAuthMiddleware;
 const sessionTokenGate_1 = require("../services/sessionTokenGate");
 const commandCaller_1 = require("./commandCaller");
@@ -66,9 +68,19 @@ exports.COMMAND_AUTH_UNAVAILABLE_BODY = {
         stacktrace: '',
     },
 };
-function decide(req, sessionId, deps) {
+/**
+ * May the caller presenting these headers use every one of these sessions?
+ *
+ * The one decision behind per-command auth, shared by the WebDriver command
+ * middleware and the session WebSocket guard (sessionUpgradeGuard.ts): an
+ * override admin may use any session, anyone else only sessions they own. A
+ * WebSocket path can name its session more than one way, so it passes every id
+ * Appium might use, and the caller must own each. Never throws: a check that
+ * could not run comes back `unavailable`.
+ */
+function decideSessionAccess(headers, sessionIds, deps) {
     return __awaiter(this, void 0, void 0, function* () {
-        const credential = (0, commandCaller_1.readPresentedCredential)(req.headers);
+        const credential = (0, commandCaller_1.readPresentedCredential)(headers);
         if (credential.kind === 'none') {
             // Nobody without credentials can be an owner or an admin: no lookups.
             return { allow: false, caller: 'no credentials', reason: 'no credentials presented' };
@@ -86,20 +98,22 @@ function decide(req, sessionId, deps) {
         const { caller } = verdict;
         if (caller.overrideAdmin)
             return { allow: true };
-        let owner;
-        try {
-            owner = yield deps.ownerOf(sessionId);
-        }
-        catch (error) {
-            return { unavailable: true, stage: 'owner lookup', error };
-        }
-        if (!owner) {
-            // Created without credentials, or no such session. Either way nobody but
-            // an override admin may drive it.
-            return { allow: false, caller: caller.userId, reason: 'no owner on record for this session' };
-        }
-        if (owner !== caller.userId) {
-            return { allow: false, caller: caller.userId, reason: 'not the session owner' };
+        for (const sessionId of sessionIds) {
+            let owner;
+            try {
+                owner = yield deps.ownerOf(sessionId);
+            }
+            catch (error) {
+                return { unavailable: true, stage: 'owner lookup', error };
+            }
+            if (!owner) {
+                // Created without credentials, or no such session. Either way nobody but
+                // an override admin may drive it.
+                return { allow: false, caller: caller.userId, reason: 'no owner on record for this session' };
+            }
+            if (owner !== caller.userId) {
+                return { allow: false, caller: caller.userId, reason: 'not the session owner' };
+            }
         }
         return { allow: true };
     });
@@ -120,7 +134,7 @@ function createCommandAuthMiddleware(deps) {
             return next();
         const sessionId = String((_b = (_a = req.params) === null || _a === void 0 ? void 0 : _a.sessionId) !== null && _b !== void 0 ? _b : '');
         const where = `${req.method} ${String((_c = req.originalUrl) !== null && _c !== void 0 ? _c : req.url).split('?')[0]}`;
-        decide(req, sessionId, deps)
+        decideSessionAccess(req.headers, [sessionId], deps)
             .then((decision) => {
             if ('unavailable' in decision) {
                 deps.logger.error(`Command auth unavailable for ${where} (session ${sessionId}): ` +

package/lib/src/middleware/csrfMiddleware.js

@@ -46,8 +46,9 @@ function csrfMiddleware(req, res, next) {
         return next();
     if (!STATE_CHANGING_METHODS.has(req.method))
         return next();
-    // Header-based auth: safe by construction (see block comment above).
-    if (req.headers['x-xenon-access-key']) {
+    // Header-based auth: safe by construction (see block comment above). A
+    // hub's signed call to its node (x-xenon-hub-token) is one too.
+    if (req.headers['x-xenon-access-key'] || req.headers['x-xenon-hub-token']) {
         return next();
     }
     // Cookie-authed (or unauthenticated) state-changer. Require Origin or

package/lib/src/middleware/deviceAccessGuard.js

@@ -21,6 +21,7 @@ const controlDevice_1 = require("./controlDevice");
 const SessionOwnerResolver_1 = require("../services/device-access/SessionOwnerResolver");
 const deviceAccessPolicy_1 = require("../services/device-access/deviceAccessPolicy");
 const actor_1 = require("../services/device-access/actor");
+const deviceClaims_1 = require("../data-service/deviceClaims");
 const STATE_CHANGING = new Set(['POST', 'PUT', 'DELETE', 'PATCH']);
 /**
  * Mutations under /control that this guard must NOT handle.
@@ -129,7 +130,9 @@ function deviceAccessGuard(deps = {}) {
             }
             const decision = (0, deviceAccessPolicy_1.evaluateDeviceAccess)({
                 udid,
-                busy: !!device.busy,
+                // Not device.busy: a node's phone busy only by its node's report is
+                // the node's to judge (heldHere).
+                busy: (0, deviceClaims_1.heldHere)(device),
                 sessionId: device.session_id,
                 sessionOwnerUserId,
                 actorUserId: actor.userId,

package/lib/src/middleware/sessionListingFilter.js

@@ -0,0 +1,153 @@
+"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 });
+exports.createSessionListingFilter = createSessionListingFilter;
+const commandCaller_1 = require("./commandCaller");
+const commandAuth_1 = require("./commandAuth");
+/**
+ * Appium 3's session listing under per-command auth.
+ *
+ * `GET <basePath>/appium/sessions` (base-driver's only listing route; Appium 3
+ * has no `GET /sessions`) answers every live session's id and capabilities.
+ * Appium gates it behind the `session_discovery` insecure feature, but once an
+ * operator enables that (Appium Inspector's "attach to session" needs it), it
+ * answers anyone, without credentials: the easiest way to find an id to use.
+ *
+ * With XENON_REQUIRE_COMMAND_AUTH on, the credentials are read exactly as for
+ * a session command (commandCaller.ts), and Appium's answer is filtered:
+ * - an override admin sees the whole list, untouched;
+ * - a verified caller sees the sessions they own, decided for the whole list
+ *   with one owner query (SessionOwnerResolver.ownersOf, ownerOf's rule);
+ * - no credentials, or credentials that do not verify: an empty list, in
+ *   Appium's normal shape, which is exactly what an idle server answers.
+ *
+ * Appium still produces the listing; this only removes entries from it, by
+ * wrapping `res.json` before the route runs. Any other answer (an error, such
+ * as session_discovery not being enabled) passes through as Appium wrote it.
+ *
+ * The owners are looked up when the listing is answered rather than before
+ * the route runs, because only then are the listed ids known. The alternative,
+ * precomputing "this caller's live sessions", has no reliable "live" signal:
+ * `xenon: setSessionStatus` changes a running session's status, and without a
+ * status filter it is every session the user ever ran.
+ *
+ * Fails closed: a credential check that cannot run answers 503 before the
+ * route runs, an owner lookup that fails answers 503 instead of the listing,
+ * and a listed entry without an id is dropped.
+ */
+/** The listed sessions in Appium's answer, or null when the answer is not a listing. */
+function listingOf(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const value = body.value;
+    return Array.isArray(value) ? value : null;
+}
+function idOf(entry) {
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    const id = entry.id;
+    return typeof id === 'string' && id ? id : undefined;
+}
+/**
+ * The listing route itself: GET, or HEAD (which Express answers from the GET
+ * route, with a Content-Length that would otherwise reveal the list's size),
+ * on the mounted path exactly. Method override has already run by now.
+ */
+function isListingRequest(req) {
+    return (req.method === 'GET' || req.method === 'HEAD') && req.path === '/';
+}
+/**
+ * Replace the listing in the route's answer with `rewrite(entries)`. The
+ * route's JSON answer is intercepted once; an answer that is not a listing is
+ * sent as the route wrote it. A rewrite that rejects answers 503.
+ */
+function rewriteListing(res, rewrite, onFailure) {
+    const json = res.json;
+    res.json = ((body) => {
+        // One answer per request: restore first, so nothing can run this twice.
+        res.json = json;
+        const entries = listingOf(body);
+        if (!entries)
+            return json.call(res, body);
+        const answer = (value) => json.call(res, Object.assign(Object.assign({}, body), { value }));
+        let rewritten;
+        try {
+            rewritten = rewrite(entries);
+        }
+        catch (error) {
+            rewritten = Promise.reject(error);
+        }
+        if (!(rewritten instanceof Promise))
+            return answer(rewritten);
+        rewritten
+            .then(answer, (error) => {
+            onFailure(error);
+            res.status(commandAuth_1.COMMAND_AUTH_UNAVAILABLE_STATUS);
+            json.call(res, commandAuth_1.COMMAND_AUTH_UNAVAILABLE_BODY);
+        })
+            .catch((error) => {
+            // Only reachable if sending itself threw; the response is past saving.
+            onFailure(error);
+        });
+        return res;
+    });
+}
+function createSessionListingFilter(deps) {
+    return (req, res, next) => {
+        var _a;
+        if (!deps.enabled() || deps.authDisabled())
+            return next();
+        if (!isListingRequest(req))
+            return next();
+        const where = `${req.method} ${String((_a = req.originalUrl) !== null && _a !== void 0 ? _a : req.url).split('?')[0]}`;
+        const showNothing = (caller, reason) => rewriteListing(res, (entries) => {
+            deps.logger.warn(`Session listing emptied: ${where} (caller ${caller}): ${reason}; ` +
+                `${entries.length} session(s) withheld.`);
+            return [];
+        }, () => undefined);
+        const showOwn = (userId) => rewriteListing(res, (entries) => __awaiter(this, void 0, void 0, function* () {
+            const ids = [...new Set(entries.map(idOf).filter((id) => !!id))];
+            const owners = ids.length > 0 ? yield deps.ownersOf(ids) : new Map();
+            const kept = entries.filter((entry) => {
+                const id = idOf(entry);
+                return !!id && owners.get(id) === userId;
+            });
+            deps.logger.info(`Session listing filtered: ${where} (caller ${userId}): ` +
+                `${kept.length} of ${entries.length} sessions shown.`);
+            return kept;
+        }), (error) => deps.logger.error(`Session listing unavailable for ${where} (caller ${userId}): ` +
+            `owner lookup failed: ${(0, commandAuth_1.summarize)(error)}`));
+        const credential = (0, commandCaller_1.readPresentedCredential)(req.headers);
+        if (credential.kind === 'none') {
+            // Nobody without credentials owns anything: no lookups.
+            showNothing('no credentials', 'no credentials presented');
+            return next();
+        }
+        deps.verifier
+            .verify(credential)
+            .then((verdict) => {
+            if (!verdict.valid)
+                showNothing('invalid credentials', 'credentials did not verify');
+            else if (!verdict.caller.overrideAdmin)
+                showOwn(verdict.caller.userId);
+            next();
+        }, (error) => {
+            deps.logger.error(`Session listing unavailable for ${where}: credential check failed: ${(0, commandAuth_1.summarize)(error)}`);
+            res.status(commandAuth_1.COMMAND_AUTH_UNAVAILABLE_STATUS).json(commandAuth_1.COMMAND_AUTH_UNAVAILABLE_BODY);
+        })
+            .catch((error) => {
+            deps.logger.error(`Session listing check failed for ${where}: ${(0, commandAuth_1.summarize)(error)}`);
+            if (!res.headersSent) {
+                res.status(commandAuth_1.COMMAND_AUTH_UNAVAILABLE_STATUS).json(commandAuth_1.COMMAND_AUTH_UNAVAILABLE_BODY);
+            }
+        });
+    };
+}

package/lib/src/middleware/sessionUpgradeGuard.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPGRADE_UNAVAILABLE_RESPONSE = exports.UPGRADE_REFUSED_RESPONSE = void 0;
+exports.sessionIdsOfUpgrade = sessionIdsOfUpgrade;
+exports.createSessionUpgradeGuard = createSessionUpgradeGuard;
+exports.guardUpgradeEvents = guardUpgradeEvents;
+const appiumBasePath_1 = require("../app/appiumBasePath");
+const commandAuth_1 = require("./commandAuth");
+/**
+ * Per-command auth for session WebSockets.
+ *
+ * WebDriver BiDi (`<basePath>/bidi/<sessionId>`, added by Appium's main) and
+ * the per-session sockets drivers add (`/ws/session/<sessionId>/...`, e.g.
+ * UiAutomator2's logcat and XCUITest's syslog broadcasts) are WebSocket
+ * upgrades. They never reach the Express routes commandAuth guards, so without
+ * this anyone who has a session id can attach to that session.
+ *
+ * With XENON_REQUIRE_COMMAND_AUTH on, an upgrade for one of those paths must
+ * carry the credentials a session command needs (the `x-xenon-*` pair or a
+ * Bearer JWT), from the session's owner or an override admin: the same
+ * decision, decideSessionAccess. Anything else is answered `404` on the raw
+ * socket, which is then closed, before Appium's handler sees it. A check that
+ * cannot run answers `503` the same way. Every other upgrade, including
+ * Xenon's own ticketed sockets (`/xenon/api/control/:udid/stream/h264`,
+ * `/logcat`) and socket.io, is left exactly as it was.
+ *
+ * Where Appium handles upgrades depends on the Node version (base-driver
+ * `server()`):
+ *
+ * - Node >= 22.21 / 24.9 (`http.Server#shouldUpgradeCallback` exists): an
+ *   `upgrade` listener on the http.Server, added before any plugin's
+ *   updateServer runs, so a plugin's own listener always comes after it.
+ * - Older Node: an Express middleware (`handleUpgrade`), ahead of the routes.
+ *   Node hands an upgrade to Express only while the server has no `upgrade`
+ *   listener at all.
+ *
+ * The check is asynchronous (a credential and an owner lookup), so being first
+ * in line is not enough: Appium's handler must not run until the answer is
+ * known. Two hooks cover both paths (registerSessionUpgradeGuard):
+ *
+ * - `guardUpgradeEvents` wraps the http.Server's `emit` for `upgrade`. A
+ *   session upgrade is held back from every listener, Appium's included, until
+ *   it is allowed, and then emitted to them unchanged. Wrapping the one call
+ *   Node makes (`server.emit('upgrade', req, socket, head)`) covers listeners
+ *   added before and after, in any order, so Appium's handler can never see a
+ *   socket this has refused, and cannot be left out if a later Appium adds its
+ *   listener later. Wrapping Appium's listener itself would miss one added
+ *   after updateServer.
+ * - `middleware`, spliced in front of the whole Express stack, holds a session
+ *   upgrade that arrives as a request the same way, and calls `next()` only
+ *   when it is allowed.
+ *
+ * Refusals are identical whether the session exists or not: without an allow,
+ * no lookup's result reaches the answer. A socket the client drops mid-check
+ * is never handed on.
+ */
+/** Appium's BiDi path (`BIDI_BASE_PATH`), under the base path. */
+const BIDI = '/bidi';
+/** base-driver's `DEFAULT_WS_PATHNAME_PREFIX`, where drivers add session sockets. */
+const DRIVER_WS = '/ws';
+/** The refusal: WebDriver's unknown session is a 404; no body, so nothing to tell apart. */
+exports.UPGRADE_REFUSED_RESPONSE = 'HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n';
+/** A credential check or owner lookup could not run. Retrying may work. */
+exports.UPGRADE_UNAVAILABLE_RESPONSE = 'HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\nContent-Length: 0\r\n\r\n';
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function decoded(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch (_a) {
+        return segment;
+    }
+}
+/**
+ * Every session id an upgrade to `url` could attach to, the way Appium would
+ * route it; empty when it attaches to no session.
+ *
+ * Appium matches its WebSocket paths with path-to-regexp against
+ * `appiumPathname(url)`: case-insensitively, with an optional trailing slash,
+ * and decoding a matched parameter. BiDi then reads the session id a second
+ * time, from the raw URL (`/bidi/([^/]+)$`, query string included). Both
+ * readings count, as do their decoded forms, and the caller must own every one
+ * of them, so no spelling of a path can name a session the check did not.
+ * An id no session has simply has no owner, and is refused.
+ *
+ * The umbrella BiDi socket (`<basePath>/bidi`) belongs to no session and is
+ * not guarded.
+ */
+function sessionIdsOfUpgrade(url, basePath) {
+    const raw = url !== null && url !== void 0 ? url : '';
+    const pathname = (0, appiumBasePath_1.appiumPathname)(raw);
+    const base = escapeRegExp((0, appiumBasePath_1.normalizeBasePath)(basePath));
+    const ids = [];
+    const bidi = new RegExp(`^${base}${BIDI}(?:/([^/]+))?/?$`, 'i').exec(pathname);
+    if (bidi) {
+        if (bidi[1])
+            ids.push(bidi[1]);
+        const appiumReading = /\/bidi\/([^/]+)$/.exec(raw);
+        if (appiumReading)
+            ids.push(appiumReading[1]);
+    }
+    // Drivers add these without the base path; accept it too, in case one does.
+    const driver = new RegExp(`^(?:${base})?${DRIVER_WS}/session/([^/]+)(?:/|$)`, 'i').exec(pathname);
+    if (driver)
+        ids.push(driver[1]);
+    return [...new Set(ids.flatMap((id) => [id, decoded(id)]))];
+}
+/** The same test Appium applies before it looks at a path. */
+function isWebSocketUpgrade(req) {
+    var _a;
+    const upgrade = (_a = req.headers) === null || _a === void 0 ? void 0 : _a.upgrade;
+    return typeof upgrade === 'string' && upgrade.toLowerCase() === 'websocket';
+}
+/** Answer on the raw socket, then close it. */
+function answerAndClose(socket, response) {
+    if (socket.destroyed)
+        return;
+    if (!socket.writable) {
+        socket.destroy();
+        return;
+    }
+    socket.once('finish', () => socket.destroy());
+    socket.end(response);
+}
+function createSessionUpgradeGuard(basePath, deps) {
+    const sessionsOf = (req) => {
+        if (!deps.enabled() || deps.authDisabled())
+            return null;
+        if (!isWebSocketUpgrade(req))
+            return null;
+        const ids = sessionIdsOfUpgrade(req.url, basePath);
+        return ids.length > 0 ? ids : null;
+    };
+    const judge = (req, socket, sessionIds, proceed) => {
+        var _a, _b;
+        const where = `upgrade ${String((_b = (_a = req.originalUrl) !== null && _a !== void 0 ? _a : req.url) !== null && _b !== void 0 ? _b : '').split('?')[0]}`;
+        const sessions = sessionIds.join(', ');
+        // Node removes its own socket error handler before it emits 'upgrade',
+        // and nothing else is listening until a WebSocket server takes the
+        // socket. A client reset during the check would otherwise be an unhandled
+        // 'error' event, which ends the process.
+        const onError = () => socket.destroy();
+        socket.on('error', onError);
+        (0, commandAuth_1.decideSessionAccess)(req.headers, sessionIds, deps)
+            .then((decision) => {
+            if ('unavailable' in decision) {
+                deps.logger.error(`Session WebSocket check unavailable for ${where} (session ${sessions}): ` +
+                    `${decision.stage} failed: ${(0, commandAuth_1.summarize)(decision.error)}`);
+                answerAndClose(socket, exports.UPGRADE_UNAVAILABLE_RESPONSE);
+                return;
+            }
+            if (!decision.allow) {
+                deps.logger.warn(`Session WebSocket refused: ${where} (session ${sessions}, caller ${decision.caller}): ` +
+                    decision.reason);
+                answerAndClose(socket, exports.UPGRADE_REFUSED_RESPONSE);
+                return;
+            }
+            // The client left while we checked: there is nothing to hand on.
+            if (socket.destroyed)
+                return;
+            socket.removeListener('error', onError);
+            proceed();
+        })
+            .catch((error) => {
+            // Only reachable if logging, answering or the handler itself threw.
+            deps.logger.error(`Session WebSocket check failed for ${where}: ${(0, commandAuth_1.summarize)(error)}`);
+            socket.destroy();
+        });
+    };
+    return {
+        hold(req, socket, proceed) {
+            const sessionIds = sessionsOf(req);
+            if (!sessionIds)
+                return false;
+            judge(req, socket, sessionIds, proceed);
+            return true;
+        },
+        middleware(req, _res, next) {
+            const sessionIds = sessionsOf(req);
+            if (!sessionIds)
+                return next();
+            judge(req, req.socket, sessionIds, () => next());
+        },
+    };
+}
+/**
+ * Route every `upgrade` event through the guard before any listener sees it
+ * (see the module comment for why `emit`). Everything else, and every upgrade
+ * the guard does not take, is emitted at once and unchanged.
+ */
+function guardUpgradeEvents(server, guard) {
+    const emit = server.emit;
+    server.emit = function emitThroughSessionGuard(event, ...args) {
+        if (event === 'upgrade') {
+            const [req, socket] = args;
+            if (guard.hold(req, socket, () => emit.call(this, event, ...args)))
+                return true;
+        }
+        return emit.call(this, event, ...args);
+    };
+}