@xenon-device-management/xenon 2.13.2 → 2.15.0

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

@@ -1483,13 +1483,20 @@ paths:
         refused, and so is a command that fails, **with `200`** and an `error` field instead of
         `output` (the dashboard's terminal prints either).
 
-        - **Android** (`adb shell`): commands starting with `ls`, `ps`, `top`, `dumpsys battery`,
-        `dumpsys wifi`, `dumpsys power`, `whoami`, `getprop`, `pm list packages`, `ip addr`, `cat
-        /proc/meminfo`, `cat /proc/cpuinfo`, `date`, `uptime` or `netstat`.
+        A command must be one of the commands below, word for word, on one line. Where it takes
+        arguments, they are plain words: letters, digits and `._/:=@%+,-`. Anything a shell would
+        interpret (`;`, `|`, `&`, `$`, backticks, quotes, `<`, `>`) is refused.
 
-        - **iOS:** simulator commands `listapps`, `get_app_container`, `list`, `getenv` (through
-        `simctl`); go-ios commands `apps`, `info`, `syslog`, `list`, `deviceinfo`, `diagnostics`;
-        and `ls`, `ps`, `top`, `whoami`, `date`, `uptime`, `netstat`, `id`.
+        - **Android** (`adb shell`): `ls`, `ps`, `top`, `getprop`, `pm list packages`, `ip addr`,
+        `date` and `netstat`, with arguments; `dumpsys battery`, `dumpsys wifi`, `dumpsys power`,
+        `whoami`, `cat /proc/meminfo`, `cat /proc/cpuinfo` and `uptime`, without.
+
+        - **iOS simulator:** `listapps`, and `get_app_container` and `getenv` with arguments
+        (through `simctl`); `ls`, `ps`, `whoami`, `date`, `uptime` and `id` without arguments
+        (spawned in the simulator).
+
+        - **Real iPhone** (go-ios, through the phone's tunnel): `apps` with arguments and `info`
+        without. Xenon names the phone; a command may not pass `--udid`.
 
         Needs the `MEMBER` role and the `devices` scope. Refused with `409` while another user holds
         the device (their live preview or recording) or runs an Appium session on it; admins are
@@ -1639,14 +1646,14 @@ paths:
       operationId: scanDeviceScreen
       summary: Analyse the screen with OCR and AI
       description: >-
-        Screenshots the device, runs OCR over it (every word with its confidence and box) and asks
-        the configured AI provider for a qualitative read of the screen. No Appium session is
-        needed. Slow: allow tens of seconds.
+        Screenshots the device, runs OCR over it (every word with its confidence and box, in the
+        screenshot's pixels) and sends the screenshot to the configured AI provider for a short
+        description of the screen. No Appium session is needed. Slow: allow tens of seconds.
 
 
         If the analysis itself fails (an empty screenshot, OCR failing), the answer is `500` with
-        `{ status: 'error', message }`. If only the AI step fails, the answer is `200` and
-        `ai_insights` is `null`.
+        `{ status: 'error', message }`. If only the AI step fails, or no AI provider is
+        configured, the answer is `200`, `ai_insights` is `null` and `ai_insights_error` says why.
 
 
         Open to watchers. Needs the `MEMBER` role; any scope will do.
@@ -1683,10 +1690,27 @@ paths:
                               y0: 210
                               x1: 188
                               y1: 236
-                      ai_insights:
-                        summary: >-
-                          A sign-in form with email and password fields and a disabled Sign in
-                          button.
+                      ai_insights: >-
+                        A sign-in screen with empty email and password fields and a disabled Sign
+                        in button. No error or dialog is shown.
+                noProvider:
+                  summary: No AI provider configured
+                  value:
+                    status: success
+                    value:
+                      timestamp: '2026-10-04T14:05:22.118Z'
+                      ocr:
+                        text: Sign in
+                        words:
+                          - text: Sign
+                            confidence: 96.2
+                            bbox:
+                              x0: 142
+                              y0: 210
+                              x1: 188
+                              y1: 236
+                      ai_insights: null
+                      ai_insights_error: No AI provider is configured
         '400':
           description: This server has no device manager for the platform, or the udid is malformed.
           content:
@@ -1745,8 +1769,9 @@ paths:
         Runs one of Xenon's AI locator strategies against a fresh screenshot, as a test would with
         `findElement`, without an Appium session.
 
-        - `-custom:ai-text`: OCR; every word containing `selector` (case-insensitive, confidence
-        above 60%).
+        - `-custom:ai-text`: OCR; every place `selector` appears (case-insensitive), within a word
+        or across neighbouring words on one line, so `Sign in` matches; each match read with
+        confidence above 60%.
 
         - `-custom:ai-icon`: the configured AI provider looks for what `selector` describes; at most
         one match, a 40×40 box around the point it names.
@@ -1939,6 +1964,30 @@ paths:
         On a hub, for a node's phone, the request is forwarded to the node, which holds the phone by
         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 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:
+          application/json:
+            schema:
+              type: object
+              properties:
+                player:
+                  type: string
+                  enum:
+                    - mjpeg
+                  description: >-
+                    Set to `mjpeg` when the page shows MJPEG. Left out, or any other value, the
+                    server chooses: H.264 for an Android device when the setting is on and the
+                    device is not being recorded, MJPEG otherwise.
+            example:
+              player: mjpeg
       responses:
         '200':
           description: The preview is running. `type` says which transport to use.
@@ -2968,10 +3017,14 @@ components:
                           y1:
                             type: number
             ai_insights:
-              type: object
+              type: string
               nullable: true
-              additionalProperties: true
-              description: The AI provider's analysis; null if it was skipped or failed.
+              description: >-
+                The AI provider's description of the screen, in plain text; null when there is no
+                AI provider or its call failed.
+            ai_insights_error:
+              type: string
+              description: Why `ai_insights` is null. Present only then.
     ControlTestLocatorRequest:
       type: object
       required:

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:
@@ -141,7 +145,8 @@ paths:
       description: |
         Sets `userBlocked` on a device, so no new session or lease is
         allocated to it. A session already running on it is not affected,
-        and neither is `busy`.
+        and neither is `busy`. The device stays blocked when it disconnects
+        and comes back, through restarts too.
 
         Send both `udid` and `host`, exactly as `GET /api/devices` shows
         them: the device is the row of that udid on that host. Without
@@ -247,7 +252,9 @@ paths:
         Replaces the device's tag list with `tags` (it doesn't append). Tags
         are free-form labels, such as `flaky` or `lab-row-3`, that a lease
         can filter on. The row is chosen by exact `udid` and `host`; a pair
-        that names no device changes nothing and still answers `200`.
+        that names no device is `404` (through 2.13 it changed nothing and
+        answered `200`). The device keeps its tags when it disconnects and
+        comes back, through restarts too.
 
         Needs role `ADMIN` and the `devices` scope.
       tags:
@@ -298,6 +305,14 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '404':
+          description: No device of that udid on that host.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: Device not found
         '429':
           $ref: '#/components/responses/RateLimited'
   /api/device/{udid}/team:
@@ -307,10 +322,14 @@ paths:
       description: |
         Gives the device to a team, or with `teamId: null` returns it to the
         shared pool, which every member sees. A missing `teamId` counts as
-        null. Every row with this udid changes (on a hub, each node that
+        null. Every device with this udid changes (on a hub, each node that
         reports it), and allocation and live dashboard events follow the new
         team at once.
 
+        A device keeps its team when it disconnects and comes back, through
+        restarts too, and this also moves one of this udid that isn't
+        connected now: a team that one belongs to can't be deleted.
+
         Needs role `ADMIN` and the `admin` scope.
       tags:
         - Devices
@@ -336,7 +355,7 @@ paths:
                   example: clx9k2v0a0000qz8r4h7m3n2p
       responses:
         '200':
-          description: The device's team changed. `updated` is how many rows changed.
+          description: The device's team changed. `updated` is how many devices changed, connected or not.
           content:
             application/json:
               schema:
@@ -432,7 +451,10 @@ paths:
         (`reservedByUserId`), who alone, or an admin, may release or extend
         it. A device already reserved by someone else, or running an Appium
         session, is refused with `409`. The same user under the same
-        `reservedBy` may reserve it again, which restarts the clock.
+        `reservedBy` may reserve it again, which restarts the clock. The
+        reservation lasts until it ends even if the device disconnects or
+        the server restarts meanwhile; one that ended while the device was
+        away is not brought back.
 
         The device is the row of `udid` on `host`, so send both exactly as
         `GET /api/devices` shows them. No such row, or a device outside the
@@ -2047,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: