@xenon-device-management/xenon 2.14.0 → 2.15.0

package/lib/src/app/dashboardPluginLink.js

@@ -0,0 +1,117 @@
+"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 });
+exports.DASHBOARD_PING_TIMEOUT_MS = exports.DASHBOARD_RETRY_MAX_MS = void 0;
+exports.ownServerOrigin = ownServerOrigin;
+exports.dashboardPluginMiddlewareFor = dashboardPluginMiddlewareFor;
+exports.dashboardPluginMiddleware = dashboardPluginMiddleware;
+const InternalHttpClient_1 = require("../InternalHttpClient");
+const logger_1 = __importDefault(require("../logger"));
+const publicUrl_1 = require("../services/publicUrl");
+/**
+ * Where the appium-dashboard-plugin is, when it runs on this Appium server
+ * (at `/dashboard`), for the device list: `request['dashboard-plugin-url']`
+ * is where Xenon itself fetches the plugin's sessions, and
+ * `request['dashboard-plugin-link']` the base of each device's
+ * `dashboard_link`, for people to open.
+ *
+ * Both come from configuration, never from a request. Through 2.14 they came
+ * from the Host header of the first /xenon/api request after startup, before
+ * the login: Xenon sent a GET to `<that host>/dashboard/api/ping`, kept
+ * `<that host>/dashboard` for the life of the process if the answer had
+ * `pong`, fetched `<that host>/dashboard/api/sessions` on every device list,
+ * and gave every user a link to that host. A forged Host made Xenon call a
+ * server of the sender's choosing and point everyone at it.
+ *
+ * - Xenon reaches the plugin on this server's own address and port
+ *   (`ownServerOrigin`, a wildcard bind address on 127.0.0.1), over HTTPS when
+ *   Appium serves it (`--ssl-certificate-path` and `--ssl-key-path`).
+ * - People get `<XENON_PUBLIC_URL>/dashboard`, or `/dashboard` on the server
+ *   their browser already has open when XENON_PUBLIC_URL isn't set.
+ *
+ * The ping is sent once, with a short time limit, and no request waits for
+ * it: a request that arrives while it is out gets no link. A plain-HTTP ping
+ * to an HTTPS server got ECONNRESET and was retried three times, about 4 s,
+ * while every signed-in request waited on it. Once it succeeds it isn't sent
+ * again; after a failure it is retried with an exponential back-off (1 s
+ * doubling to 30 s), so a server without the plugin doesn't ping on every
+ * request.
+ */
+exports.DASHBOARD_RETRY_MAX_MS = 30000;
+/** How long the ping may take. It goes to this same server. */
+exports.DASHBOARD_PING_TIMEOUT_MS = 2000;
+/**
+ * A server's own origin from its bind address and port; a wildcard is reached
+ * on 127.0.0.1. `tls` when Appium serves HTTPS.
+ */
+function ownServerOrigin(address, port, tls = false) {
+    const wildcard = !address || address === '0.0.0.0' || address === '::';
+    const host = wildcard ? '127.0.0.1' : address.includes(':') ? `[${address}]` : address;
+    return `${tls ? 'https' : 'http'}://${host}:${port}`;
+}
+/**
+ * The middleware for this server: its bind address, port and whether Appium
+ * serves HTTPS, from Appium's CLI arguments. The ping is sent once
+ * (`retry: false`) with DASHBOARD_PING_TIMEOUT_MS.
+ */
+function dashboardPluginMiddlewareFor(ownServer) {
+    const config = {
+        silent: true,
+        retry: false,
+        timeout: exports.DASHBOARD_PING_TIMEOUT_MS,
+    };
+    return dashboardPluginMiddleware({
+        ownServerOrigin: ownServerOrigin(ownServer.address, ownServer.port, ownServer.tls),
+        get: (url) => InternalHttpClient_1.InternalHttpClient.get(url, config),
+        warn: (message) => logger_1.default.warn(message),
+    });
+}
+function dashboardPluginMiddleware(deps) {
+    var _a, _b;
+    const now = (_a = deps.now) !== null && _a !== void 0 ? _a : Date.now;
+    const publicBase = (_b = deps.publicBase) !== null && _b !== void 0 ? _b : (() => (0, publicUrl_1.publicServerBase)());
+    const pluginUrl = `${deps.ownServerOrigin}/dashboard`;
+    let present = false;
+    let pinging = false;
+    let nextRetryAt = 0;
+    let retryDelayMs = 1000;
+    const ping = () => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        try {
+            const response = yield deps.get(`${pluginUrl}/api/ping`);
+            if (response && response['pong'])
+                return true;
+        }
+        catch (err) {
+            (_a = deps.warn) === null || _a === void 0 ? void 0 : _a.call(deps, `[Xenon] Dashboard ping failed, retrying in ${retryDelayMs}ms: ${(err === null || err === void 0 ? void 0 : err.message) || err}`);
+        }
+        nextRetryAt = now() + retryDelayMs;
+        retryDelayMs = Math.min(retryDelayMs * 2, exports.DASHBOARD_RETRY_MAX_MS);
+        return false;
+    });
+    return (req, _res, next) => {
+        var _a;
+        if (!present && !pinging && now() >= nextRetryAt) {
+            // One ping at a time, and nobody waits for it.
+            pinging = true;
+            void ping().then((ok) => {
+                present = ok;
+                pinging = false;
+            });
+        }
+        req['dashboard-plugin-url'] = present ? pluginUrl : '';
+        req['dashboard-plugin-link'] = present ? `${(_a = publicBase()) !== null && _a !== void 0 ? _a : ''}/dashboard` : '';
+        next();
+    };
+}

package/lib/src/app/index.js

@@ -54,7 +54,6 @@ const pluginArgs_1 = require("../data-service/pluginArgs");
 const cors_1 = __importDefault(require("cors"));
 const async_lock_1 = __importDefault(require("async-lock"));
 const crypto_1 = __importDefault(require("crypto"));
-const InternalHttpClient_1 = require("../InternalHttpClient");
 const logger_1 = __importStar(require("../logger"));
 const sessionContext_1 = require("../logging/sessionContext");
 const dashboard_1 = __importDefault(require("./routers/dashboard"));
@@ -91,7 +90,7 @@ const PluginContext_1 = require("../PluginContext");
 const nodeWebDriverUrl_1 = require("../gateway/nodeWebDriverUrl");
 const nodeSessionStatus_1 = require("../gateway/nodeSessionStatus");
 const nodeSessionMetrics_1 = require("../gateway/nodeSessionMetrics");
-const dashboardPluginUrl = null;
+const dashboardPluginLink_1 = require("./dashboardPluginLink");
 const ASYNC_LOCK = new async_lock_1.default();
 // An async handler's error reaches the error handlers, as on Express 5.
 (0, apiErrors_1.forwardAsyncErrors)();
@@ -148,37 +147,6 @@ apiRouter.use((req, res, next) => {
     res.setHeader('Expires', '0');
     next();
 });
-// Dashboard state cache - runs once and persists on success.
-// On failure we back off exponentially (1s → 2s → 4s → … capped at 30s)
-// so a down dashboard doesn't turn every API request into a fresh ping.
-let dashboardPluginPromise = null;
-let dashboardNextRetryAt = 0;
-let dashboardRetryDelayMs = 1000;
-const DASHBOARD_RETRY_MAX_MS = 30000;
-apiRouter.use((req, res, next) => __awaiter(void 0, void 0, void 0, function* () {
-    if (dashboardPluginPromise === null && Date.now() >= dashboardNextRetryAt) {
-        dashboardPluginPromise = (() => __awaiter(void 0, void 0, void 0, function* () {
-            const pingurl = `${req.protocol}://${req.get('host')}/dashboard/api/ping`;
-            try {
-                const response = yield InternalHttpClient_1.InternalHttpClient.get(pingurl, { silent: true });
-                if (response && response['pong']) {
-                    dashboardRetryDelayMs = 1000;
-                    dashboardNextRetryAt = 0;
-                    return `${req.protocol}://${req.get('host')}/dashboard`;
-                }
-            }
-            catch (err) {
-                logger_1.default.warn(`[Xenon] Dashboard ping failed, retrying in ${dashboardRetryDelayMs}ms: ${(err === null || err === void 0 ? void 0 : err.message) || err}`);
-            }
-            dashboardNextRetryAt = Date.now() + dashboardRetryDelayMs;
-            dashboardRetryDelayMs = Math.min(dashboardRetryDelayMs * 2, DASHBOARD_RETRY_MAX_MS);
-            dashboardPluginPromise = null;
-            return '';
-        }))();
-    }
-    req['dashboard-plugin-url'] = dashboardPluginPromise ? yield dashboardPluginPromise : '';
-    return next();
-}));
 const findPublicPath = () => {
     const rootDir = path_1.default.resolve(__dirname, '..', '..');
     const searchPaths = [
@@ -227,7 +195,13 @@ router.use('/api', apiRouter);
 // express.static mount here, outside the login, which also served every
 // recording and interceptor capture stored under the same folder.
 router.use(staticFilesRouter);
-function createRouter(pluginArgs) {
+/**
+ * `ownServer` is this Appium server's bind address and port, and whether it
+ * serves HTTPS (from its CLI arguments). With it, the device list links to an appium-dashboard-plugin on
+ * this server (dashboardPluginLink.ts); without it, as in specs that build a
+ * router alone, there is none.
+ */
+function createRouter(pluginArgs, ownServer) {
     // CSRF defense (runs before /health so even a hostile GET->POST confused-
     // deputy has no soft target). Pass-through for GETs, for header-authed
     // callers, and when authDisabled=true. Returns 403 for cookie-authed
@@ -254,6 +228,11 @@ function createRouter(pluginArgs) {
     // provisioned.
     apiRouter.use(authMiddleware_1.authMiddleware);
     apiRouter.use((0, rateLimitMiddleware_1.rateLimitMiddleware)());
+    // The appium-dashboard-plugin's address, for the device list, from this
+    // server's own address and XENON_PUBLIC_URL. Never from a request: it was
+    // built from the Host header of the first request, before the login.
+    if (ownServer)
+        apiRouter.use((0, dashboardPluginLink_1.dashboardPluginMiddlewareFor)(ownServer));
     // Authenticated auth endpoints: /me, /change-password, /dashboard-session
     apiRouter.use('/auth', (0, auth_1.authAuthedRouter)());
     // Admin: API key management

package/lib/src/app/openapi/control.yaml

@@ -1965,10 +1965,12 @@ paths:
         its own rules; on success the hub also marks the phone busy and held by you at once. A cloud
         provider's phone answers `501`.
 
-        One capture runs per Android device. A page that shows MJPEG (a browser that cannot decode
-        H.264, which on plain http it cannot, or a page whose H.264 player failed) sends
-        `player: mjpeg`: the server then starts the MJPEG capture, and first ends an H.264 capture
-        already running for the device, so the two never run together.
+        One capture per Android device where it can be. A page that shows MJPEG (a browser that
+        cannot decode H.264, which on plain http it cannot, or a page whose H.264 player failed)
+        sends `player: mjpeg`: the server then starts the MJPEG capture, and ends an H.264 capture
+        running for the device once nobody plays it: first, if nobody does, else when its last
+        viewer leaves. Another page may still be playing it, and keeps it until then. A node on
+        2.13 or older ignores `player`.
       requestBody:
         required: false
         content:

package/lib/src/app/openapi/grid.yaml

@@ -16,7 +16,11 @@ paths:
         `session_id` is that value, as an object, or an empty `200` body
         when there is none. When the Appium dashboard plugin is installed,
         each row in the list also gets `dashboard_link` and
-        `total_session_count`.
+        `total_session_count`. Xenon reaches the plugin on this server's own
+        address and port, and the link is `<XENON_PUBLIC_URL>/dashboard?…`,
+        or `/dashboard?…` on the server the caller has open when
+        `XENON_PUBLIC_URL` isn't set. Through 2.14 both were built from the
+        `Host` header of the first request after startup, signed in or not.
 
         `GET /api/device` is the same endpoint.
       tags:
@@ -2065,7 +2069,9 @@ components:
               description: On a hub, the preview hold the node last reported (`manual_<userId>_<udid>`).
             dashboard_link:
               type: string
-              description: Only with the Appium dashboard plugin installed.
+              description: >-
+                Only with the Appium dashboard plugin installed: the plugin's page for this device,
+                under `XENON_PUBLIC_URL`, or a path on this server when it isn't set.
             total_session_count:
               type: integer
               description: Only with the Appium dashboard plugin installed.

package/lib/src/app/openapi/identity.yaml

@@ -10,9 +10,10 @@ paths:
         Public. Tells the sign-in page how a user who forgot their password can get back in, before
         anyone is signed in.
 
-        `passwordReset` is `email` when the server has SMTP configured (the forgot-password form
-        really emails a link), otherwise `admin` (the user must ask an administrator, who issues a
-        link with `POST /api/users/{id}/reset-link`). Nothing else about the mail setup is revealed.
+        `passwordReset` is `email` when the server has SMTP configured and `XENON_PUBLIC_URL` set to
+        its address (the forgot-password form really emails a link, which points there),
+        otherwise `admin` (the user must ask an administrator, who issues a link with
+        `POST /api/users/{id}/reset-link`). Nothing else about the mail setup is revealed.
       tags:
         - Authentication
       security: []
@@ -34,8 +35,8 @@ paths:
         Public. Checks the email (case-insensitive) and password of an `ACTIVE` user and, on success,
         sets the `xenon_dashboard_session` cookie (HttpOnly, `SameSite=Strict`, `Secure` when the
         request came over HTTPS or with `X-Forwarded-Proto: https`). The cookie lives for the
-        server's user-session lifetime (24 hours by default, `XENON_USER_SESSION_TTL_MS`) and is
-        renewed on every authenticated request. Updates the user's last sign-in time.
+        server's user-session lifetime (24 hours by default, `XENON_USER_SESSION_TTL_MS`, which may be
+        longer or shorter) and is renewed for that long on every authenticated request. Updates the user's last sign-in time.
 
         A wrong password, an unknown email and an inactive user all answer the same `401`.
 
@@ -116,8 +117,11 @@ paths:
         addresses have accounts. Then, in the background, if the email belongs to an `ACTIVE` user and
         the server can deliver mail (SMTP configured, or the opt-in log fallback
         `XENON_PASSWORD_RESET_LOG_FALLBACK=true`), it creates a single-use reset token (valid 1 hour by
-        default) and sends a link to `/xenon/reset-password#<token>`. Without either, no token is created;
-        `GET /api/auth/options` says `admin` in that case.
+        default, `XENON_RESET_TOKEN_TTL_MS`) and sends a link to
+        `<server address>/xenon/reset-password#<token>`. The server address is `XENON_PUBLIC_URL`
+        (such as `https://xenon.example.com`; a trailing `/xenon/` is dropped), never the request's
+        `Host`, which whoever asks chooses. Without a way to deliver mail, or without a usable
+        `XENON_PUBLIC_URL`, no token is created; `GET /api/auth/options` says `admin` then.
 
         **Rate limit.** 3 requests per 15 minutes per client IP by default, then `429` with
         `Retry-After`.
@@ -387,16 +391,28 @@ paths:
           (`XENON_MCP_TOKEN_TTL_SEC`). It carries granular `scopes` (by default `appium:use` and
           `xenon:devices:read`, as far as the caller's scopes allow) and, as a REST bearer token, only
           the flat scopes those need (`appium:use` gives `sessions`, `xenon:devices:lock` gives
-          `devices`). The answer also has a `sessionToken` (audience `xenon-session`, same lifetime)
-          to put in an Appium session's `xe:options.sessionToken`.
+          `devices`). When the grant includes `appium:use` the answer also has a `sessionToken`
+          (audience `xenon-session`, same lifetime) to put in an Appium session's
+          `xe:options.sessionToken`. It carries the `sessions` scope, and `admin` only when the
+          credential minting it has `admin` and the grant is the default one (no `scopes` asked for) or
+          a full-admin one. With `admin` a session may use a lease someone else made, and only while
+          its user is still an `ADMIN` (a `SUPER_ADMIN`'s session may, `admin` or not). A credential
+          without `sessions` or `admin`, a read-only one for instance, gets no `sessionToken`.
+
+        **Never longer than the credential.** A token minted with a Bearer token, or with an API key
+        that expires, ends no later than that credential: `expiresIn` is cut to what is left of it. A
+        credential with no time left answers `400`. A dashboard sign-in renews itself, so its tokens get
+        the full lifetime.
+
+        **Scopes follow the role.** A token's scopes are fixed when it is minted, but its `admin` scope
+        stops counting once its user is a `MEMBER`: the API and per-command auth read the token's scopes
+        without it.
 
         Granular scopes a credential may grant: `read` gives `xenon:devices:read` and
         `xenon:analytics:read`; `sessions` gives `appium:use` and `xenon:recordings`; `devices` gives
         `xenon:devices:read`, `xenon:devices:lock` and `xenon:recordings`; `admin` gives all of them.
 
-        Cookie callers need a same-host `Origin` or `Referer`. So, as the server is written, does a
-        caller using only `Authorization: Bearer`: the same-origin check exempts only requests with an
-        `x-xenon-access-key` header.
+        Cookie callers need a same-host `Origin` or `Referer`.
       tags:
         - Authentication
       requestBody:
@@ -441,7 +457,9 @@ paths:
                       - xenon:devices:read
                     sessionToken: eyJhbGciOiJSUzI1NiIsImtpZCI6IjNmMmE5YzRlN2QxYiJ9.eyJzdWIiOiI3YzFlMmQ0YSIsImF1ZCI6Inhlbm9uLXNlc3Npb24ifQ.c2lnbmF0dXJl
         '400':
-          description: An unsupported audience, `scopes` that isn't an array, or an unknown granular scope.
+          description: |
+            An unsupported audience, `scopes` that isn't an array, an unknown granular scope, or a
+            credential with no time left to give the token.
           content:
             application/json:
               schema:
@@ -451,6 +469,10 @@ paths:
                   value:
                     error: bad_request
                     details: 'unsupported audience: xenon-node'
+                expired:
+                  value:
+                    error: bad_request
+                    details: the credential used to mint this token has expired
                 unknownScope:
                   value:
                     error: unknown_scope
@@ -584,8 +606,12 @@ paths:
       description: |
         Gives the caller a new access key. The old one stops working at once, for every one of their
         API tokens: scripts and CI using the key pair must be updated. The tokens themselves are kept.
-        Any signed-in user may call it; with authentication disabled it rotates the first
-        `SUPER_ADMIN`'s key. Cookie callers need a same-host `Origin` or `Referer`.
+
+        Since that cuts off every key pair the user has, whatever its scopes, it takes a dashboard
+        sign-in (the cookie) or a credential with the `admin` scope. Any other API token or Bearer
+        token, a `read`-only one for instance, gets `403`. Through 2.14 any credential could. With
+        authentication disabled it rotates the first `SUPER_ADMIN`'s key. Cookie callers need a
+        same-host `Origin` or `Referer`.
       tags:
         - Profile
       responses:
@@ -600,7 +626,13 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
-          $ref: '#/components/responses/Forbidden'
+          description: A credential other than a dashboard sign-in, without the `admin` scope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: rotating the access key needs a dashboard sign-in or a credential with the admin scope
         '404':
           $ref: '#/components/responses/IdentityUserNotFound'
         '429':
@@ -653,6 +685,11 @@ paths:
         role was checked, so an admin's `read`-only key could mint a wider token. The token has the
         default rate limit (300 a minute) and no team binding.
 
+        Made with a credential that expires (a Bearer token, or an API key with an `expiresAt`), the
+        token expires no later than it: without `expiresAt` it gets that credential's, and a later
+        `expiresAt` answers `400`. Through 2.14 a 1-hour Bearer token could make a token that never
+        expired. From the dashboard, `expiresAt` may be left out for a token that never expires.
+
         Any signed-in user may call it. Cookie callers need a same-host `Origin` or `Referer`.
       tags:
         - Profile
@@ -681,8 +718,8 @@ paths:
                 expiresAt: '2027-01-01T00:00:00.000Z'
         '400':
           description: >-
-            `name` is missing, `expiresAt` is invalid or past, a scope is unknown, or a scope is
-            beyond your role or the credential you are using.
+            `name` is missing, `expiresAt` is invalid, past or later than the credential you are
+            using, a scope is unknown, or a scope is beyond your role or the credential you are using.
           content:
             application/json:
               schema:
@@ -694,6 +731,11 @@ paths:
                 expiry:
                   value:
                     error: expiresAt must be in the future
+                outlives:
+                  value:
+                    error: >-
+                      expiresAt can be no later than the credential you are using, which expires at
+                      2026-10-04T13:00:00.000Z
                 unknown:
                   value:
                     error: scopes must be some of read, sessions, devices, admin
@@ -872,7 +914,9 @@ paths:
         - You can't change your own role.
         - The last active `SUPER_ADMIN` can't be demoted or deactivated.
         - Setting `status` to `INACTIVE` signs the user out of every dashboard session. Their API
-          tokens and bearer tokens stop working too, since an inactive user's credentials are refused.
+          tokens, bearer tokens and session tokens stop working too, since an inactive user's
+          credentials are refused: on this API at once, for a new Appium session at once, and for the
+          commands of a session already running within 30 seconds with `XENON_REQUIRE_COMMAND_AUTH`.
 
         Cookie callers need a same-host `Origin` or `Referer`.
       tags:
@@ -973,9 +1017,11 @@ paths:
         Needs role `ADMIN` or above. An `ADMIN` may issue links only for `MEMBER` accounts. Creates a
         single-use reset link for an `ACTIVE` user, valid 1 hour by default.
 
-        With SMTP configured the link is emailed to the user and the answer is `emailed: true`.
-        Without it the link is returned once, in this answer only (`Cache-Control: no-store`), for the
-        admin to pass on; it is never written to the server log. Your own password goes through
+        With SMTP and `XENON_PUBLIC_URL` configured the link is emailed to the user and the answer is
+        `emailed: true`; the emailed link points at `XENON_PUBLIC_URL`, never at the request's `Host`.
+        Without either the link is returned once, in this answer only (`Cache-Control: no-store`), for
+        the admin to pass on; it is never written to the server log. A returned link points at
+        `XENON_PUBLIC_URL` when it is set, else at the address the admin reached the server on. Your own password goes through
         `POST /api/auth/change-password` instead. Cookie callers need a same-host `Origin` or
         `Referer`.
       tags:
@@ -1322,10 +1368,20 @@ paths:
       summary: Create an API key
       description: |
         Creates an API token owned by the caller and returns its value **once** as `key`; it is used as
-        `x-xenon-token` with the caller's access key. Unlike `POST /api/profile/tokens`, it can bind the
-        key to a team (the key then sees that team's devices only, within its owner's teams), set its
-        rate limit and grant any scope, `admin` included. Needs role `ADMIN` or above and the `admin`
-        scope. Cookie callers need a same-host `Origin` or `Referer`.
+        `x-xenon-token` with the caller's access key. Unlike `POST /api/profile/tokens`, it can name a
+        team, set its rate limit and grant any scope, `admin` included. `scopes` must be some of `read`,
+        `sessions`, `devices` and `admin`; any other string answers `400` (through 2.14 it was stored,
+        and gave the key nothing). Needs role `ADMIN` or above and the `admin` scope. Cookie callers
+        need a same-host `Origin` or `Referer`.
+
+        **The team doesn't narrow the key.** The key belongs to the caller, an administrator, and an
+        administrator's credentials reach every team's devices, so the key does too whichever team it
+        names. The team is recorded on the leases the key takes, and limits the key only if its owner
+        is later made a `MEMBER`. A test session keeps to one team with `xe:options.team`.
+
+        Made with a credential that expires (a Bearer token, or an API key with an `expiresAt`), the
+        key expires no later than it: without `expiresAt` it gets that credential's, and a later
+        `expiresAt` answers `400`.
       tags:
         - API Keys
       requestBody:
@@ -1365,7 +1421,9 @@ paths:
                 key: 5d2e8f1a9c4b7e3d6a0f2c8b1e5d9a4c7f3b6e0d2a8c5f1e9b4d7a3c6f0e2b8d
                 expiresAt: '2027-04-01T00:00:00.000Z'
         '400':
-          description: '`name` or `scopes` is missing, or `expiresAt` is invalid or past.'
+          description: >-
+            `name` or `scopes` is missing, a scope is unknown, or `expiresAt` is invalid, past or later
+            than the credential making the request.
           content:
             application/json:
               schema:
@@ -1374,6 +1432,9 @@ paths:
                 missing:
                   value:
                     error: name and scopes required
+                unknown:
+                  value:
+                    error: scopes must be some of read, sessions, devices, admin
                 expiry:
                   value:
                     error: expiresAt must be an ISO-8601 datetime
@@ -1835,7 +1896,9 @@ components:
             type: string
         sessionToken:
           type: string
-          description: '`xenon-mcp` only: a session token for `xe:options.sessionToken`, with the same lifetime.'
+          description: >-
+            `xenon-mcp` only, and only when the grant includes `appium:use`: a session token for
+            `xe:options.sessionToken`, with the same lifetime.
     IdentityAccessKey:
       type: object
       properties:
@@ -1881,7 +1944,10 @@ components:
           type: string
           format: date-time
           nullable: true
-          description: When the token stops working; must be in the future. Null or absent for never.
+          description: >-
+            When the token stops working; must be in the future, and no later than the credential
+            making the request when that one expires. Null or absent for never, or, with a credential
+            that expires, for when that credential does.
     IdentityCreatedToken:
       type: object
       properties:
@@ -2099,12 +2165,18 @@ components:
         teamId:
           type: string
           nullable: true
-          description: Bind the key to this team.
+          description: >-
+            A team to note on the key. The key belongs to the caller, an administrator, so like them it
+            reaches every team's devices whichever team this names: the team is recorded on the leases
+            the key takes, and limits the key only if its owner is later made a `MEMBER`.
         expiresAt:
           type: string
           format: date-time
           nullable: true
-          description: When the key stops working; must be in the future. Null or absent for never.
+          description: >-
+            When the key stops working; must be in the future, and no later than the credential
+            making the request when that one expires. Null or absent for never, or, with a credential
+            that expires, for when that credential does.
     IdentityProject:
       type: object
       properties:

package/lib/src/app/openapi/platform.yaml

@@ -188,9 +188,11 @@ paths:
       summary: Read the lab's settings and AI provider
       description: |
         The lab-wide settings in effect (health checks, build cleanup and the AI self-healing
-        switch), merged with the AI settings currently in effect. Each setting is the value saved
-        in the dashboard, else the plugin option the server was started with, else the default,
-        which is also what the server runs with. `defaults` holds the defaults themselves, which
+        switch), merged with the AI settings in effect (provider, models and base URL). Each
+        setting is the value saved in the dashboard, else the plugin option or environment
+        variable the server was started with, else the default, which is also what the server
+        runs with. A model or base URL set nowhere is absent: the provider's own applies. A user
+        name, password or query value in the base URL is sent as `***`. `defaults` holds the defaults themselves, which
         is what "restore defaults" goes back to. Only `healthCheckSchedule` can be absent: no
         schedule is set. Through 2.13 `enableSelfHealing` was neither stored nor sent, so the
         Settings page always showed it on.
@@ -266,10 +268,18 @@ paths:
           switch was accepted and ignored. The value belongs to the server it is saved on:
           saving it on a hub changes the hub's own sessions, not those on a node's phones,
           which the node's own setting decides.
-        - AI fields (`aiProvider`, `aiModel`, `aiBaseUrl` and the per-provider models) change the
-          running server only. They are not stored, so a restart returns to the values the
-          server was started with. API keys can't be set here; they come from the server's
-          environment.
+        - AI fields (`aiProvider`, `aiModel`, `aiBaseUrl` and the per-provider models) are stored
+          too. A stored value replaces the plugin option or environment variable the server was
+          started with, and applies to the next AI call, with no restart. An empty value removes
+          the stored one, and the server's own applies again. They are checked first and refused
+          with `400`: `aiProvider` must be `gemini`, `openai`, `anthropic` or `ollama`; a model
+          name has no spaces and at most 200 characters; `aiBaseUrl` is an http or https address
+          with no user name, password or query. Through 2.14 they changed the running server
+          only, and a restart undid them. Like the self-healing switch, they belong to the server
+          they are saved on.
+        - API keys can't be set here, and are never stored: they come from the server's
+          environment. `aiTemperature`, `aiMaxTokens` and `aiTopP`, which the AI engine page sent
+          through 2.14, were never used by any AI call and are ignored like any unknown field.
 
         Needs the `SUPER_ADMIN` role and the `admin` scope; an `ADMIN` gets `403` with a message
         saying so (through 2.12 an `ADMIN` could). With the dashboard cookie the request must
@@ -299,7 +309,7 @@ paths:
               example:
                 success: true
         '400':
-          description: A build-cleanup field or the self-healing switch has a value that could not work. Nothing was saved.
+          description: A build-cleanup field, the self-healing switch or an AI field has a value that could not work. Nothing was saved.
           content:
             application/json:
               schema:
@@ -2387,6 +2397,7 @@ components:
               type: boolean
         aiProvider:
           type: string
+          description: The provider in effect, saved on the AI engine page, else the server's option or environment, else gemini.
           example: gemini
         aiModel:
           type: string
@@ -2438,30 +2449,37 @@ components:
           type: boolean
         aiProvider:
           type: string
-          description: Not stored; until the server restarts.
+          description: The provider every AI call uses. Stored; empty goes back to the server's own.
           enum:
             - gemini
             - openai
             - anthropic
             - ollama
+            - ''
         aiModel:
           type: string
-          description: Not stored; until the server restarts.
+          description: The model for a provider with no model of its own below. Stored; empty goes back to the server's own.
+          maxLength: 200
         aiBaseUrl:
           type: string
-          description: Not stored; until the server restarts.
+          description: Where OpenAI-compatible and Ollama calls go. An http or https address with no user name, password or query. Stored; empty goes back to the server's own.
+          example: http://gpu-box.lab:11434
         geminiModel:
           type: string
-          description: Not stored; until the server restarts.
+          description: Stored; empty goes back to the server's own.
+          maxLength: 200
         openaiModel:
           type: string
-          description: Not stored; until the server restarts.
+          description: Stored; empty goes back to the server's own.
+          maxLength: 200
         anthropicModel:
           type: string
-          description: Not stored; until the server restarts.
+          description: Stored; empty goes back to the server's own.
+          maxLength: 200
         ollamaModel:
           type: string
-          description: Not stored; until the server restarts.
+          description: Stored; empty goes back to the server's own.
+          maxLength: 200
     PlatformAiTestRequest:
       type: object
       description: Every field is optional and falls back to the server's current setting.