@xenon-device-management/xenon 2.0.0 → 2.2.0

package/lib/public/assets/{users-CEJ3fC78.js → users-Nb_rzRmF.js}

@@ -1,4 +1,4 @@
-import{c as w,b as k,r as a,j as e,$ as C}from"./index-BR1wTIPC.js";import{l as M,d as R,c as I,a as A,u as D}from"./users-Drd7ifJx.js";import{f as U}from"./time-B8FIgwPE.js";import{P}from"./page-header-CP2UkykG.js";import{B as y}from"./button-xtAhYR-f.js";import{I as N}from"./input-DejcCiTI.js";import{S as g}from"./select-Uc9E5pye.js";import{P as B}from"./plus-BTD0dnQ0.js";import{T as L}from"./trash-2-BorJv5_u.js";import"./utils-CDN07tui.js";/**
+import{c as w,b as k,r as a,j as e,$ as C}from"./index-3uxl3o7K.js";import{l as M,d as R,c as I,a as A,u as D}from"./users-BU0nXIVe.js";import{f as U}from"./time-B8FIgwPE.js";import{P}from"./page-header-CfR4Sm9V.js";import{B as y}from"./button-_Y78wXiP.js";import{I as N}from"./input-CzTWvUXZ.js";import{S as g}from"./select-Cqx7pEou.js";import{P as B}from"./plus-DOS8P9CQ.js";import{T as L}from"./trash-2-BV4hSmXJ.js";import"./utils-CDN07tui.js";/**
  * @license lucide-react v0.555.0 - ISC
  *
  * This source code is licensed under the ISC license.

package/lib/public/assets/{video-off-CNzn6bPE.js → video-off-CUNzD2kH.js}

@@ -1,4 +1,4 @@
-import{c as o}from"./index-BR1wTIPC.js";/**
+import{c as o}from"./index-3uxl3o7K.js";/**
  * @license lucide-react v0.555.0 - ISC
  *
  * This source code is licensed under the ISC license.

package/lib/public/assets/{webhook-settings-BFqX6QXV.js → webhook-settings-Ca3UFXZe.js}

@@ -1 +1 @@
-import{t as P,r,X as c,j as e,J as u,A as b,C as U,K as D}from"./index-BR1wTIPC.js";/* empty css                 */import{F as S}from"./FieldGroup-BduMPM9K.js";import{P as O}from"./page-header-CP2UkykG.js";import{T as V}from"./trash-2-BorJv5_u.js";import{P as x}from"./plus-BTD0dnQ0.js";import{C as B}from"./circle-x-CZH6t9z-.js";import{C as H}from"./circle-check-CZdg8mMa.js";import{Z as I}from"./zap-4yN8Jdfw.js";import{A as J}from"./activity-D17TUloi.js";const C=[{id:"device_offline",label:"Device offline",icon:U,tone:"red"},{id:"device_new",label:"New device",icon:x,tone:"green"},{id:"session_failed",label:"Session failed",icon:B,tone:"amber"},{id:"selector_health_digest",label:"Selector health digest",icon:D,tone:"green"}],X=["udid","host","name","sessionId","failureReason","eventType","platform"],ae=()=>{const{toast:o}=P(),[g,T]=r.useState([]),[A,w]=r.useState(!0),[l,j]=r.useState(""),[d,k]=r.useState(["device_offline","session_failed"]),[h,f]=r.useState(!1),[v,N]=r.useState(!1),[n,_]=r.useState(!1),[y,m]=r.useState("");r.useEffect(()=>{p()},[]);const p=async()=>{w(!0);try{const s=await c.getWebhookConfigs();T(s||[])}catch(s){console.error("Failed to load webhook configs",s),o("Failed to load webhooks.","error")}finally{w(!1)}},z=async()=>{if(!l.trim()){o("Webhook URL is required.","error");return}if(d.length===0){o("Select at least one trigger event.","error");return}f(!0);try{await c.addWebhookConfig(l.trim(),d,"slack",y||void 0),j(""),m(""),_(!1),k(["device_offline","session_failed"]),await p(),o("Webhook saved.","success")}catch(s){console.error("Failed to add webhook",s),o(`Failed to add webhook: ${s.message||"unknown error"}`,"error")}finally{f(!1)}},E=async(s,t)=>{if(window.confirm(`Remove webhook for "${t}"?`))try{await c.deleteWebhookConfig(s),await p(),o("Webhook removed.","success")}catch(a){console.error("Failed to delete webhook",a),o(`Failed to delete: ${a.message||"unknown error"}`,"error")}},L=async()=>{if(l.trim()){N(!0);try{await c.testWebhook(l.trim(),"slack"),o("Test payload delivered.","success")}catch(s){o(`Test failed: ${s.message||"check the URL"}`,"error")}finally{N(!1)}}},$=s=>{k(t=>t.includes(s)?t.filter(a=>a!==s):[...t,s])},R=s=>{m(t=>t+`{{${s}}} `)};return e.jsxs("div",{className:"settings-container",children:[e.jsx(O,{icon:u,title:"Notifications",subtitle:"Configure Slack or generic webhooks to receive alerts for critical infrastructure events."}),e.jsxs("div",{className:"settings-content",children:[A?e.jsxs("div",{className:"settings-loading",style:{height:200},children:[e.jsx(b,{className:"animate-spin",size:28}),e.jsx("span",{children:"Loading webhooks…"})]}):g.length===0?e.jsxs("div",{className:"empty-state",children:[e.jsx("div",{className:"empty-state__icon",children:e.jsx(u,{size:28})}),e.jsx("h3",{className:"empty-state__title",children:"No webhooks configured"}),e.jsx("p",{className:"empty-state__copy",children:"Wire up a Slack incoming webhook or any HTTPS endpoint to receive alerts when devices go offline, new devices register, or sessions fail. Configure your first webhook below."})]}):e.jsx("div",{className:"webhook-list-grid",children:g.map(s=>{const t=(()=>{try{return JSON.parse(s.events)}catch{return[]}})();return e.jsxs("div",{className:"webhook-row-card",children:[e.jsxs("div",{className:"webhook-row-card__header",children:[e.jsx("span",{className:`pill-chip ${s.payloadTemplate?"pill-chip--admin":"pill-chip--scope"}`,children:s.payloadTemplate?"CUSTOM":"SLACK"}),e.jsx("span",{className:"webhook-row-card__url",title:s.url,children:s.url}),e.jsxs("button",{type:"button",className:"row-action row-action--danger",onClick:()=>E(s.id,s.url),"aria-label":`Remove webhook for ${s.url}`,children:[e.jsx(V,{size:13}),e.jsx("span",{children:"Remove"})]})]}),e.jsx("div",{className:"webhook-row-card__events",children:t.length===0?e.jsx("span",{className:"webhook-row-card__no-events",children:"No triggers"}):t.map(a=>{const i=C.find(F=>F.id===a),W=(i==null?void 0:i.icon)??u;return e.jsxs("span",{className:`event-pill event-pill--${(i==null?void 0:i.tone)||"gray"}`,children:[e.jsx(W,{size:11}),(i==null?void 0:i.label)||a]},a)})})]},s.id)})}),e.jsxs("div",{className:"add-webhook-card",children:[e.jsxs("div",{className:"add-webhook-card__header",children:[e.jsx(x,{size:14}),e.jsx("span",{children:"Add a new webhook"})]}),e.jsxs("div",{className:"add-webhook-card__body",children:[e.jsx(S,{label:"Webhook URL",description:"The endpoint we POST webhook events to.",htmlFor:"webhook-url",children:e.jsx("div",{className:"setting-input-wrapper",children:e.jsx("input",{id:"webhook-url",type:"url",placeholder:"https://hooks.slack.com/services/...",value:l,onChange:s=>j(s.target.value)})})}),e.jsx(S,{label:"Trigger events",children:e.jsx("div",{className:"event-toggle-grid",children:C.map(s=>{const t=d.includes(s.id),a=s.icon;return e.jsxs("button",{type:"button",role:"checkbox","aria-checked":t,className:`event-toggle event-toggle--${s.tone} ${t?"is-selected":""}`,onClick:()=>$(s.id),children:[e.jsx(a,{size:14,className:"event-toggle__lead"}),e.jsx("span",{children:s.label}),t&&e.jsx(H,{size:14,className:"event-toggle__check"})]},s.id)})})}),e.jsxs("div",{className:"template-section",children:[e.jsxs("button",{type:"button",className:"template-section__toggle",onClick:()=>_(!n),"aria-expanded":n,children:[e.jsx(I,{size:14,className:n?"tone-amber":"tone-dim"}),e.jsx("span",{children:"Use custom payload (optional)"}),e.jsx("span",{className:"template-section__indicator",children:n?"−":"+"})]}),n&&e.jsxs("div",{className:"template-editor",children:[e.jsx("p",{className:"template-editor__hint",children:"Define a JSON or text template. Click a variable below to insert it."}),e.jsx("div",{className:"template-editor__chips",children:X.map(s=>e.jsx("button",{type:"button",className:"template-editor__chip",onClick:()=>R(s),children:`{{${s}}}`},s))}),e.jsx("textarea",{className:"template-editor__textarea",placeholder:'Example: { "text": "Alert: Device {{udid}} is offline!" }',value:y,onChange:s=>m(s.target.value),rows:4})]})]})]}),e.jsxs("div",{className:"add-webhook-card__footer",children:[e.jsxs("button",{type:"button",className:"page-header-action page-header-action--ghost",onClick:L,disabled:!l.trim()||v,children:[v?e.jsx(b,{size:14,className:"animate-spin"}):e.jsx(J,{size:14}),e.jsx("span",{children:"Test payload"})]}),e.jsxs("button",{type:"button",className:"page-header-action",onClick:z,disabled:h||!l.trim(),children:[h?e.jsx(b,{size:14,className:"animate-spin"}):e.jsx(x,{size:14}),e.jsx("span",{children:h?"Saving…":"Save webhook"})]})]})]})]})]})};export{ae as WebhookSettings};
+import{t as P,r,X as c,j as e,J as u,A as b,C as U,K as D}from"./index-3uxl3o7K.js";/* empty css                 */import{F as S}from"./FieldGroup-5bCutWrs.js";import{P as O}from"./page-header-CfR4Sm9V.js";import{T as V}from"./trash-2-BV4hSmXJ.js";import{P as x}from"./plus-DOS8P9CQ.js";import{C as B}from"./circle-x-B4IOD1DE.js";import{C as H}from"./circle-check-D3Qq0tKp.js";import{Z as I}from"./zap-B2bH2vKX.js";import{A as J}from"./activity-DxRFWvkN.js";const C=[{id:"device_offline",label:"Device offline",icon:U,tone:"red"},{id:"device_new",label:"New device",icon:x,tone:"green"},{id:"session_failed",label:"Session failed",icon:B,tone:"amber"},{id:"selector_health_digest",label:"Selector health digest",icon:D,tone:"green"}],X=["udid","host","name","sessionId","failureReason","eventType","platform"],ae=()=>{const{toast:o}=P(),[g,T]=r.useState([]),[A,w]=r.useState(!0),[l,j]=r.useState(""),[d,k]=r.useState(["device_offline","session_failed"]),[h,f]=r.useState(!1),[v,N]=r.useState(!1),[n,_]=r.useState(!1),[y,m]=r.useState("");r.useEffect(()=>{p()},[]);const p=async()=>{w(!0);try{const s=await c.getWebhookConfigs();T(s||[])}catch(s){console.error("Failed to load webhook configs",s),o("Failed to load webhooks.","error")}finally{w(!1)}},z=async()=>{if(!l.trim()){o("Webhook URL is required.","error");return}if(d.length===0){o("Select at least one trigger event.","error");return}f(!0);try{await c.addWebhookConfig(l.trim(),d,"slack",y||void 0),j(""),m(""),_(!1),k(["device_offline","session_failed"]),await p(),o("Webhook saved.","success")}catch(s){console.error("Failed to add webhook",s),o(`Failed to add webhook: ${s.message||"unknown error"}`,"error")}finally{f(!1)}},E=async(s,t)=>{if(window.confirm(`Remove webhook for "${t}"?`))try{await c.deleteWebhookConfig(s),await p(),o("Webhook removed.","success")}catch(a){console.error("Failed to delete webhook",a),o(`Failed to delete: ${a.message||"unknown error"}`,"error")}},L=async()=>{if(l.trim()){N(!0);try{await c.testWebhook(l.trim(),"slack"),o("Test payload delivered.","success")}catch(s){o(`Test failed: ${s.message||"check the URL"}`,"error")}finally{N(!1)}}},$=s=>{k(t=>t.includes(s)?t.filter(a=>a!==s):[...t,s])},R=s=>{m(t=>t+`{{${s}}} `)};return e.jsxs("div",{className:"settings-container",children:[e.jsx(O,{icon:u,title:"Notifications",subtitle:"Configure Slack or generic webhooks to receive alerts for critical infrastructure events."}),e.jsxs("div",{className:"settings-content",children:[A?e.jsxs("div",{className:"settings-loading",style:{height:200},children:[e.jsx(b,{className:"animate-spin",size:28}),e.jsx("span",{children:"Loading webhooks…"})]}):g.length===0?e.jsxs("div",{className:"empty-state",children:[e.jsx("div",{className:"empty-state__icon",children:e.jsx(u,{size:28})}),e.jsx("h3",{className:"empty-state__title",children:"No webhooks configured"}),e.jsx("p",{className:"empty-state__copy",children:"Wire up a Slack incoming webhook or any HTTPS endpoint to receive alerts when devices go offline, new devices register, or sessions fail. Configure your first webhook below."})]}):e.jsx("div",{className:"webhook-list-grid",children:g.map(s=>{const t=(()=>{try{return JSON.parse(s.events)}catch{return[]}})();return e.jsxs("div",{className:"webhook-row-card",children:[e.jsxs("div",{className:"webhook-row-card__header",children:[e.jsx("span",{className:`pill-chip ${s.payloadTemplate?"pill-chip--admin":"pill-chip--scope"}`,children:s.payloadTemplate?"CUSTOM":"SLACK"}),e.jsx("span",{className:"webhook-row-card__url",title:s.url,children:s.url}),e.jsxs("button",{type:"button",className:"row-action row-action--danger",onClick:()=>E(s.id,s.url),"aria-label":`Remove webhook for ${s.url}`,children:[e.jsx(V,{size:13}),e.jsx("span",{children:"Remove"})]})]}),e.jsx("div",{className:"webhook-row-card__events",children:t.length===0?e.jsx("span",{className:"webhook-row-card__no-events",children:"No triggers"}):t.map(a=>{const i=C.find(F=>F.id===a),W=(i==null?void 0:i.icon)??u;return e.jsxs("span",{className:`event-pill event-pill--${(i==null?void 0:i.tone)||"gray"}`,children:[e.jsx(W,{size:11}),(i==null?void 0:i.label)||a]},a)})})]},s.id)})}),e.jsxs("div",{className:"add-webhook-card",children:[e.jsxs("div",{className:"add-webhook-card__header",children:[e.jsx(x,{size:14}),e.jsx("span",{children:"Add a new webhook"})]}),e.jsxs("div",{className:"add-webhook-card__body",children:[e.jsx(S,{label:"Webhook URL",description:"The endpoint we POST webhook events to.",htmlFor:"webhook-url",children:e.jsx("div",{className:"setting-input-wrapper",children:e.jsx("input",{id:"webhook-url",type:"url",placeholder:"https://hooks.slack.com/services/...",value:l,onChange:s=>j(s.target.value)})})}),e.jsx(S,{label:"Trigger events",children:e.jsx("div",{className:"event-toggle-grid",children:C.map(s=>{const t=d.includes(s.id),a=s.icon;return e.jsxs("button",{type:"button",role:"checkbox","aria-checked":t,className:`event-toggle event-toggle--${s.tone} ${t?"is-selected":""}`,onClick:()=>$(s.id),children:[e.jsx(a,{size:14,className:"event-toggle__lead"}),e.jsx("span",{children:s.label}),t&&e.jsx(H,{size:14,className:"event-toggle__check"})]},s.id)})})}),e.jsxs("div",{className:"template-section",children:[e.jsxs("button",{type:"button",className:"template-section__toggle",onClick:()=>_(!n),"aria-expanded":n,children:[e.jsx(I,{size:14,className:n?"tone-amber":"tone-dim"}),e.jsx("span",{children:"Use custom payload (optional)"}),e.jsx("span",{className:"template-section__indicator",children:n?"−":"+"})]}),n&&e.jsxs("div",{className:"template-editor",children:[e.jsx("p",{className:"template-editor__hint",children:"Define a JSON or text template. Click a variable below to insert it."}),e.jsx("div",{className:"template-editor__chips",children:X.map(s=>e.jsx("button",{type:"button",className:"template-editor__chip",onClick:()=>R(s),children:`{{${s}}}`},s))}),e.jsx("textarea",{className:"template-editor__textarea",placeholder:'Example: { "text": "Alert: Device {{udid}} is offline!" }',value:y,onChange:s=>m(s.target.value),rows:4})]})]})]}),e.jsxs("div",{className:"add-webhook-card__footer",children:[e.jsxs("button",{type:"button",className:"page-header-action page-header-action--ghost",onClick:L,disabled:!l.trim()||v,children:[v?e.jsx(b,{size:14,className:"animate-spin"}):e.jsx(J,{size:14}),e.jsx("span",{children:"Test payload"})]}),e.jsxs("button",{type:"button",className:"page-header-action",onClick:z,disabled:h||!l.trim(),children:[h?e.jsx(b,{size:14,className:"animate-spin"}):e.jsx(x,{size:14}),e.jsx("span",{children:h?"Saving…":"Save webhook"})]})]})]})]})]})};export{ae as WebhookSettings};

package/lib/public/assets/{zap-4yN8Jdfw.js → zap-B2bH2vKX.js}

@@ -1,4 +1,4 @@
-import{c as a}from"./index-BR1wTIPC.js";/**
+import{c as a}from"./index-3uxl3o7K.js";/**
  * @license lucide-react v0.555.0 - ISC
  *
  * This source code is licensed under the ISC license.

package/lib/public/index.html

@@ -36,7 +36,7 @@
       Learn how to configure a non-root public URL by running `npm run build`.
     -->
   <title>Xenon</title>
-  <script type="module" crossorigin src="/xenon/assets/index-BR1wTIPC.js"></script>
+  <script type="module" crossorigin src="/xenon/assets/index-3uxl3o7K.js"></script>
   <link rel="stylesheet" crossorigin href="/xenon/assets/index-hymrhlEZ.css">
 </head>
 

package/lib/src/InternalHttpClient.js

@@ -55,7 +55,8 @@ const logger_1 = __importDefault(require("./logger"));
  *
  * Features:
  * - Keep-alive connections for performance
- * - Automatic retry with exponential backoff
+ * - Automatic retry with exponential backoff, except for a request that sets
+ *   `retry: false` (InternalRequestConfig)
  * - Request/response logging for debugging
  * - Correlation ID tracking
  */
@@ -178,6 +179,9 @@ class InternalHttpClient {
                 logger_1.default.warn(`[HTTP ←] ${(_c = config === null || config === void 0 ? void 0 : config.method) === null || _c === void 0 ? void 0 : _c.toUpperCase()} ${config === null || config === void 0 ? void 0 : config.url} ` +
                     `[${status || 'ERR'}] ${duration}ms - ${error.message}`);
             }
+            if (config.retry === false) {
+                return Promise.reject(error);
+            }
             const decision = InternalHttpClient.classifyRetry(error);
             if (!decision.retryable || config.retryCount >= InternalHttpClient.MAX_RETRIES) {
                 return Promise.reject(error);

package/lib/src/XenonCapabilityManager.js

@@ -206,9 +206,23 @@ function iOSCapabilities(caps, freeDevice) {
         deleteMatch.forEach((value) => deleteAlwaysMatch(caps, value));
     });
 }
+/**
+ * The team a session asks to be placed in, or undefined. Documented as
+ * `xe:options.team` (`teamId` is read too), with `xenon:options` as the
+ * alias, through xenonOptionsOf like every other Xenon option. The flat caps
+ * older clients send (`xenon:team`, `xe:teamId`, ...) still work; an options
+ * field wins over them. `df:` is never read.
+ *
+ * The merge is field by field, so if a request spells it `team` in one
+ * namespace and `teamId` in the other, `team` wins.
+ */
 function extractTeamCap(caps) {
     var _a;
-    const merged = Object.assign({}, ((_a = caps.firstMatch) === null || _a === void 0 ? void 0 : _a[0]) || {}, caps.alwaysMatch || {});
+    const options = (0, xenonOptions_1.xenonOptionsOf)(caps);
+    const fromOptions = (_a = (0, xenonOptions_1.stringOption)(options, 'team')) !== null && _a !== void 0 ? _a : (0, xenonOptions_1.stringOption)(options, 'teamId');
+    if (fromOptions)
+        return fromOptions;
+    const merged = (0, xenonOptions_1.mergedFirstMatch)(caps);
     const prefixes = ['xenon:', 'xe:', 'appium:', ''];
     const names = ['teamId', 'team_id', 'team'];
     for (const prefix of prefixes) {

package/lib/src/app/appiumBasePath.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBasePath = normalizeBasePath;
+exports.appiumPathname = appiumPathname;
+/**
+ * Appium's base-path rule (base-driver `normalizeBasePath`): drop one trailing
+ * '/', and add a leading '/' unless the path is empty. `cliArgs.basePath`
+ * reaches a plugin as the operator wrote it, while Appium normalises its own
+ * copy before building routes and WebSocket paths, so anything placed in front
+ * of those must normalise the same way or it would miss what it guards.
+ */
+function normalizeBasePath(basePath) {
+    let normalized = typeof basePath === 'string' ? basePath : '';
+    normalized = normalized.replace(/\/$/, '');
+    if (normalized !== '' && !normalized.startsWith('/'))
+        normalized = `/${normalized}`;
+    return normalized;
+}
+/**
+ * The pathname Appium matches an upgrade against, computed as
+ * base-driver's tryHandleWebSocketUpgrade does: WHATWG URL parsing, which
+ * resolves dot segments (also `%2e%2e`) and drops the query and an absolute
+ * form's host.
+ */
+function appiumPathname(url) {
+    try {
+        return new URL(url, 'http://localhost').pathname;
+    }
+    catch (_a) {
+        return url;
+    }
+}

package/lib/src/app/index.js

@@ -86,6 +86,9 @@ const rateLimitMiddleware_1 = require("../middleware/rateLimitMiddleware");
 const csrfMiddleware_1 = require("../middleware/csrfMiddleware");
 const swagger_1 = require("./swagger");
 const typedi_1 = require("typedi");
+const PluginContext_1 = require("../PluginContext");
+const nodeWebDriverUrl_1 = require("../gateway/nodeWebDriverUrl");
+const nodeSessionStatus_1 = require("../gateway/nodeSessionStatus");
 const dashboardPluginUrl = null;
 const ASYNC_LOCK = new async_lock_1.default();
 const router = express_1.default.Router(), apiRouter = express_1.default.Router(), staticFilesRouter = express_1.default.Router();
@@ -228,6 +231,15 @@ function createRouter(pluginArgs) {
     apiRouter.use(csrfMiddleware_1.csrfMiddleware);
     // Health endpoint: no auth, no rate limit
     apiRouter.get('/health', (_req, res) => res.json({ ok: true }));
+    // Where this server's WebDriver API lives: a hub asks a node before sending
+    // it a session or a command (gateway/nodeWebDriverUrl.ts). No login: the
+    // hub holds no credentials for the node, and the base path is in every
+    // client's URL anyway.
+    apiRouter.get('/webdriver', (0, nodeWebDriverUrl_1.webdriverInfoHandler)(() => typedi_1.Container.get(PluginContext_1.PluginContext).nodeBasePath));
+    // On a node: whether a session exists, for the hub's heartbeat, answered
+    // without sending the session a command. No login (the hub holds no
+    // credentials for the node); it takes the hub's session token instead.
+    (0, nodeSessionStatus_1.registerNodeSessionStatus)(apiRouter, pluginArgs);
     // Dashboard login: unauthenticated (rate-limited internally via separate IP logic)
     apiRouter.use('/auth', (0, auth_1.authPublicRouter)()); // login, logout — unauthenticated
     // All remaining /api/* requires authentication (cookie session for

package/lib/src/app/insertBeforeRoutes.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.routerStackOf = routerStackOf;
 exports.insertBeforeRoutes = insertBeforeRoutes;
+exports.insertAtStart = insertAtStart;
 function isRouter(candidate) {
     return !!candidate && Array.isArray(candidate.stack);
 }
@@ -28,7 +29,11 @@ function routerStackOf(app) {
     var _a;
     return (_a = findRouter(app)) === null || _a === void 0 ? void 0 : _a.router.stack;
 }
-function insertBeforeRoutes(app, path, handler) {
+/**
+ * Let `app.use()` build one layer, then move it to `positionOf(stack)` (the
+ * stack without the new layer).
+ */
+function spliceNewLayer(app, use, positionOf) {
     const found = findRouter(app);
     if (!found) {
         return {
@@ -38,7 +43,7 @@ function insertBeforeRoutes(app, path, handler) {
     }
     const { stack } = found.router;
     const lengthBefore = stack.length;
-    app.use(path, handler);
+    use();
     const added = stack.splice(lengthBefore);
     if (added.length !== 1) {
         // app.use() added its layer somewhere other than the stack we found, or
@@ -50,8 +55,23 @@ function insertBeforeRoutes(app, path, handler) {
             reason: `app.use() added ${added.length} layers to the router stack, expected 1`,
         };
     }
-    const firstRoute = stack.findIndex((layer) => !!layer.route);
-    const index = firstRoute === -1 ? stack.length : firstRoute;
+    const index = positionOf(stack);
     stack.splice(index, 0, added[0]);
     return { placed: true, shape: found.shape, index };
 }
+function insertBeforeRoutes(app, path, handler) {
+    return spliceNewLayer(app, () => app.use(path, handler), (stack) => {
+        const firstRoute = stack.findIndex((layer) => !!layer.route);
+        return firstRoute === -1 ? stack.length : firstRoute;
+    });
+}
+/**
+ * Put a path-less middleware at the very front of the router stack, ahead of
+ * middleware as well as routes. For a check that must run before one of
+ * Appium's own middlewares (its WebSocket `handleUpgrade`), which sit ahead of
+ * the routes. On Express 4 that is also ahead of `query` and `expressInit`, so
+ * the handler must use only Node's own request and response API.
+ */
+function insertAtStart(app, handler) {
+    return spliceNewLayer(app, () => app.use(handler), () => 0);
+}

package/lib/src/app/registerCommandAuth.js

@@ -1,67 +1,186 @@
 "use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeBasePath = normalizeBasePath;
+exports.normalizeBasePath = void 0;
 exports.sessionCommandPath = sessionCommandPath;
+exports.sessionListingPath = sessionListingPath;
+exports.commandAuthDeps = commandAuthDeps;
+exports.sessionCreatePath = sessionCreatePath;
+exports.registerSessionGateway = registerSessionGateway;
 exports.registerCommandAuth = registerCommandAuth;
+exports.registerSessionUpgradeGuard = registerSessionUpgradeGuard;
 const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../logger"));
 const config_1 = require("../config");
 const SessionOwnerResolver_1 = require("../services/device-access/SessionOwnerResolver");
 const commandAuth_1 = require("../middleware/commandAuth");
 const commandCaller_1 = require("../middleware/commandCaller");
+const sessionListingFilter_1 = require("../middleware/sessionListingFilter");
+const sessionUpgradeGuard_1 = require("../middleware/sessionUpgradeGuard");
+const internalCall_1 = require("../gateway/internalCall");
+const sessionGateway_1 = require("../gateway/sessionGateway");
+const sessionCreate_1 = require("../gateway/sessionCreate");
+const appiumBasePath_1 = require("./appiumBasePath");
+Object.defineProperty(exports, "normalizeBasePath", { enumerable: true, get: function () { return appiumBasePath_1.normalizeBasePath; } });
 const insertBeforeRoutes_1 = require("./insertBeforeRoutes");
-/**
- * Appium's base-path rule (base-driver `normalizeBasePath`): drop one trailing
- * '/', and add a leading '/' unless the path is empty. `cliArgs.basePath`
- * reaches a plugin as the operator wrote it, while Appium normalises its own
- * copy before building routes, so the guard must normalise the same way or it
- * would miss the routes it is meant to sit in front of.
- */
-function normalizeBasePath(basePath) {
-    let normalized = typeof basePath === 'string' ? basePath : '';
-    normalized = normalized.replace(/\/$/, '');
-    if (normalized !== '' && !normalized.startsWith('/'))
-        normalized = `/${normalized}`;
-    return normalized;
-}
 /**
  * Everything under `<basePath>/session/:sessionId`, every method. The create
  * route (`POST <basePath>/session`) has no id segment and does not match.
  */
 function sessionCommandPath(basePath) {
-    return `${normalizeBasePath(basePath)}/session/:sessionId`;
+    return `${(0, appiumBasePath_1.normalizeBasePath)(basePath)}/session/:sessionId`;
+}
+/** Appium 3's session listing route (base-driver `getAppiumSessions`). */
+function sessionListingPath(basePath) {
+    return `${(0, appiumBasePath_1.normalizeBasePath)(basePath)}/appium/sessions`;
 }
 /**
- * Install per-command auth (commandAuth.ts) ahead of Appium's routes. Called
- * from ServerManager.registerRoutes, which Appium runs after adding them.
+ * The dependencies per-command auth runs with. ServerManager builds one set
+ * and hands it to both registrations below, so commands, the session listing
+ * and session WebSockets share one credential cache.
+ */
+function commandAuthDeps(overrides = {}) {
+    var _a, _b, _c, _d, _e, _f;
+    return {
+        enabled: (_a = overrides.enabled) !== null && _a !== void 0 ? _a : (() => (0, commandAuth_1.commandAuthEnabled)()),
+        authDisabled: (_b = overrides.authDisabled) !== null && _b !== void 0 ? _b : (() => config_1.config.authDisabled === true),
+        verifier: (_c = overrides.verifier) !== null && _c !== void 0 ? _c : new commandCaller_1.CommandCallerVerifier(),
+        ownerOf: (_d = overrides.ownerOf) !== null && _d !== void 0 ? _d : ((sessionId) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).ownerOf(sessionId)),
+        ownersOf: (_e = overrides.ownersOf) !== null && _e !== void 0 ? _e : ((sessionIds) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).ownersOf(sessionIds)),
+        logger: (_f = overrides.logger) !== null && _f !== void 0 ? _f : logger_1.default.scope('CommandAuth'),
+    };
+}
+const refuseToStart = (what) => new Error(`XENON_REQUIRE_COMMAND_AUTH is on, but ${what}. Refusing to start rather than ` +
+    'serve sessions unchecked.');
+/** The create route (`POST <basePath>/session`), where the create layer is mounted. */
+function sessionCreatePath(basePath) {
+    return `${(0, appiumBasePath_1.normalizeBasePath)(basePath)}/session`;
+}
+/**
+ * Install the session gateway (gateway/sessionGateway.ts) and the
+ * session-listing filter (sessionListingFilter.ts) ahead of Appium's routes.
+ * Called from ServerManager.registerRoutes, which Appium runs after adding
+ * them. The gateway is three adjacent layers:
+ *
+ * 1. the internal-call layer (gateway/internalCall.ts), path-less, which turns
+ *    Xenon's own `<basePath>/wd-internal/...` calls, when they carry this
+ *    process's secret, into the plain session command;
+ * 2. with `options.create`, the create layer at `<basePath>/session`
+ *    (gateway/sessionCreate.ts), which allocates the phone for
+ *    `POST <basePath>/session` and creates a remote phone's session itself;
+ * 3. the session layer at `<basePath>/session/:sessionId`: per-command auth,
+ *    then, on a hub, forwarding of the sessions other servers run.
+ *
+ * The first comes first, so the others see an internal call by its real path
+ * and know it for one. It is path-less because Express puts a mount path back
+ * onto the URL when a mounted layer calls next(), which would undo the strip.
+ * The others are mounted, so their path matching is the router's own.
+ *
+ * All of it is always installed and reads the setting per request, so a
+ * server with per-command auth off pays one env check per session command and
+ * does no lookups for it. If a layer cannot be placed ahead of the routes the
+ * error is logged, and with the setting on (and auth enabled) the server
+ * refuses to start: an operator who asked for the check must not get a server
+ * that silently serves session commands without it.
  *
- * The middleware is always installed and reads the setting per request, so a
- * server with the setting off pays one env check per session command and does
- * no lookups. If it cannot be placed ahead of the routes the error is logged,
- * and with the setting on (and auth enabled) the server refuses to start:
- * an operator who asked for the check must not get a server that silently
- * serves session commands without it.
+ * Returns where the session layer was placed.
  */
-function registerCommandAuth(app, cliArgs, overrides = {}) {
-    const deps = Object.assign({ enabled: () => (0, commandAuth_1.commandAuthEnabled)(), authDisabled: () => config_1.config.authDisabled === true, verifier: new commandCaller_1.CommandCallerVerifier(), ownerOf: (sessionId) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).ownerOf(sessionId), logger: logger_1.default.scope('CommandAuth') }, overrides);
-    const path = sessionCommandPath(cliArgs === null || cliArgs === void 0 ? void 0 : cliArgs.basePath);
-    const result = (0, insertBeforeRoutes_1.insertBeforeRoutes)(app, path, (0, commandAuth_1.createCommandAuthMiddleware)(deps));
+function registerSessionGateway(app, cliArgs, deps, options = {}) {
+    var _a;
     const active = deps.enabled() && !deps.authDisabled();
+    const basePath = (0, appiumBasePath_1.normalizeBasePath)(cliArgs === null || cliArgs === void 0 ? void 0 : cliArgs.basePath);
+    const { create } = options, gateway = __rest(options, ["create"]);
+    const path = sessionCommandPath(basePath);
+    const internal = (0, insertBeforeRoutes_1.insertBeforeRoutes)(app, '/', (0, internalCall_1.createInternalCallLayer)(basePath));
+    const created = internal.placed && create
+        ? (0, insertBeforeRoutes_1.insertBeforeRoutes)(app, sessionCreatePath(basePath), (0, sessionCreate_1.createSessionCreateLayer)(Object.assign(Object.assign({}, create), { authDisabled: deps.authDisabled, logger: (_a = create.logger) !== null && _a !== void 0 ? _a : deps.logger })))
+        : internal;
+    const result = created.placed
+        ? (0, insertBeforeRoutes_1.insertBeforeRoutes)(app, path, (0, sessionGateway_1.createSessionGatewayLayer)(Object.assign(Object.assign({}, gateway), { auth: deps })))
+        : created;
     if (!result.placed) {
         deps.logger.error(`Per-command auth could not be placed ahead of Appium's routes for ${path}: ${result.reason}.`);
         if (active) {
-            throw new Error('XENON_REQUIRE_COMMAND_AUTH is on, but the per-command check could not be placed ahead ' +
-                "of Appium's WebDriver routes, so it would never run. Refusing to start rather than " +
-                'serve session commands unchecked.');
+            throw refuseToStart("the per-command check could not be placed ahead of Appium's WebDriver routes, " +
+                'so it would never run');
+        }
+        return result;
+    }
+    const listingPath = sessionListingPath(cliArgs === null || cliArgs === void 0 ? void 0 : cliArgs.basePath);
+    const listing = (0, insertBeforeRoutes_1.insertBeforeRoutes)(app, listingPath, (0, sessionListingFilter_1.createSessionListingFilter)(deps));
+    if (!listing.placed) {
+        deps.logger.error("The session-listing filter could not be placed ahead of Appium's routes for " +
+            `${listingPath}: ${listing.reason}.`);
+        if (active) {
+            throw refuseToStart(`the session-listing filter could not be placed ahead of ${listingPath}`);
         }
         return result;
     }
     deps.logger.info(active
         ? `Per-command auth is ON: every request under ${path} needs the session owner's ` +
-            'credentials or an override admin (XENON_REQUIRE_COMMAND_AUTH).'
-        : `Per-command auth is off for ${path} (XENON_REQUIRE_COMMAND_AUTH not set, or auth disabled).`);
+            `credentials or an override admin, and ${listingPath} lists only the caller's ` +
+            'sessions (XENON_REQUIRE_COMMAND_AUTH).'
+        : `Per-command auth is off for ${path} and ${listingPath} ` +
+            '(XENON_REQUIRE_COMMAND_AUTH not set, or auth disabled).');
     return result;
 }
+/**
+ * Per-command auth (commandAuth.ts) and the session-listing filter, through the
+ * session gateway with no routing: a server that runs every session itself.
+ */
+function registerCommandAuth(app, cliArgs, overrides = {}) {
+    return registerSessionGateway(app, cliArgs, commandAuthDeps(overrides));
+}
+/**
+ * Install the session WebSocket guard (sessionUpgradeGuard.ts) on both of the
+ * paths Appium can take an upgrade by: the http.Server's `upgrade` event and
+ * the front of the Express stack. Called from ServerManager.updateServer with
+ * the http.Server Appium hands plugins.
+ *
+ * Like registerCommandAuth, it is always installed and reads the setting per
+ * upgrade; with the setting off every upgrade passes straight through. If
+ * either hook cannot be installed the error is logged, and with the setting on
+ * the server refuses to start.
+ */
+function registerSessionUpgradeGuard(httpServer, app, cliArgs, overrides = {}) {
+    const deps = commandAuthDeps(overrides);
+    const active = deps.enabled() && !deps.authDisabled();
+    const basePath = (0, appiumBasePath_1.normalizeBasePath)(cliArgs === null || cliArgs === void 0 ? void 0 : cliArgs.basePath);
+    const guard = (0, sessionUpgradeGuard_1.createSessionUpgradeGuard)(basePath, deps);
+    const problems = [];
+    if (httpServer && typeof httpServer.emit === 'function') {
+        (0, sessionUpgradeGuard_1.guardUpgradeEvents)(httpServer, guard);
+    }
+    else {
+        problems.push('no HTTP server was given to guard');
+    }
+    const front = (0, insertBeforeRoutes_1.insertAtStart)(app, guard.middleware);
+    if (!front.placed)
+        problems.push(`the Express guard was not placed: ${front.reason}`);
+    if (problems.length > 0) {
+        const reason = problems.join('; ');
+        deps.logger.error(`The session WebSocket guard could not be installed: ${reason}.`);
+        if (active) {
+            throw refuseToStart(`session WebSockets (${basePath}/bidi/<id>, /ws/session/<id>/...) could not be guarded`);
+        }
+        return { placed: false, shape: front.shape, reason };
+    }
+    deps.logger.info(active
+        ? `Session WebSocket guard is ON: upgrades to ${basePath}/bidi/:sessionId and ` +
+            "/ws/session/:sessionId/... need the session owner's credentials or an override admin."
+        : 'Session WebSocket guard is off (XENON_REQUIRE_COMMAND_AUTH not set, or auth disabled).');
+    return front;
+}