@xenon-device-management/xenon 2.14.0 → 2.15.0

package/lib/src/services/omni-vision/OmniVisionService.js

@@ -1,43 +1,10 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -52,22 +19,36 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 var OmniVisionService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OmniVisionService = void 0;
+exports.OmniVisionService = exports.MAX_VIRTUAL_ELEMENTS = exports.MAX_VIRTUAL_ELEMENTS_PER_SESSION = void 0;
 const typedi_1 = require("typedi");
-const tesseract_js_1 = __importStar(require("tesseract.js"));
+const tesseract_js_1 = require("tesseract.js");
+const ocrData_1 = require("../ocr/ocrData");
 const sharp_1 = __importDefault(require("sharp"));
 const AIService_1 = require("../AIService");
 const logger_1 = __importDefault(require("../../logger"));
 const crypto_1 = __importDefault(require("crypto"));
 const ocrTextMatch_1 = require("./ocrTextMatch");
 const screenScale_1 = require("./screenScale");
+/**
+ * How many virtual elements Xenon keeps, for one session and in all. The
+ * oldest go first: a test acts on what it found last, and a command on an
+ * element that went answers "no such element".
+ */
+exports.MAX_VIRTUAL_ELEMENTS_PER_SESSION = 1000;
+exports.MAX_VIRTUAL_ELEMENTS = 10000;
 // Mobile UIs have sparse text on complex backgrounds - reduce contrast to preserve readability
 const DEFAULT_CONTRAST = 1.2; // Slightly above 1.0 for mild enhancement (was 0.8 which was too aggressive)
 const UPSCALE_THRESHOLD = 800; // Only upscale very small images (was 1500)
 let OmniVisionService = OmniVisionService_1 = class OmniVisionService {
     constructor() {
         this.logger = logger_1.default.scope('OmniVision');
-        this.virtualElementStore = new Map();
+        /**
+         * The virtual elements tests may still act on, by id, each with the session
+         * that found it, oldest first. Through 2.14 every element ever found stayed
+         * here until the server restarted, and any session could act on another's.
+         */
+        this.elements = new Map();
+        this.bySession = new Map();
         this.sharedWorker = null;
         this.workerBusy = false;
         this.uiLensCache = new Map();
@@ -77,7 +58,7 @@ let OmniVisionService = OmniVisionService_1 = class OmniVisionService {
             if (this.sharedWorker)
                 return this.sharedWorker;
             this.logger.info('Initializing persistent OCR worker with explicit configuration...');
-            const worker = yield tesseract_js_1.default.createWorker('eng');
+            const worker = yield (0, ocrData_1.createOcrWorker)();
             // PSM.SPARSE_TEXT is optimized for irregular text layouts like mobile UIs
             // AUTO mode assumes document structure which fails on sparse mobile screens
             yield worker.setParameters({
@@ -385,6 +366,21 @@ let OmniVisionService = OmniVisionService_1 = class OmniVisionService {
     wordBoxes(words) {
         return words.map((w) => this.normalizeWordBBox(w)).filter(Boolean);
     }
+    /** Where `text` is among OCR's words, read with over 60% confidence, in reading order. */
+    textMatches(words, text) {
+        return (0, ocrTextMatch_1.findText)(this.wordBoxes(words), String(text !== null && text !== void 0 ? text : '')).filter((m) => m.confidence > 60);
+    }
+    /**
+     * Where `text` is on a screenshot, matched as `-custom:ai-text` matches it:
+     * in the screenshot's pixels, in reading order. Self-healing's OCR tier
+     * uses it. Throws when OCR fails.
+     */
+    findTextInScreenshot(screenshotBase64, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { words } = yield this.performOcr(Buffer.from(screenshotBase64, 'base64'));
+            return this.textMatches(words, text);
+        });
+    }
     /**
      * Proactive OCR Search: Finds elements matching text even if not in XML.
      *
@@ -407,20 +403,16 @@ let OmniVisionService = OmniVisionService_1 = class OmniVisionService {
                     this.logger.warn(`OCR proactive search yielded no words. Text content: "${ocrText.trim().substring(0, 100)}..."`);
                     return [];
                 }
-                const matches = (0, ocrTextMatch_1.findText)(this.wordBoxes(words), String(text !== null && text !== void 0 ? text : '')).filter((m) => m.confidence > 60);
+                const matches = this.textMatches(words, text);
                 if (matches.length === 0)
                     return [];
                 const scale = yield (0, screenScale_1.screenScaleOf)(driver, screenshot);
-                return matches.map((m) => {
-                    const el = {
-                        id: `omni_ocr_${Date.now()}_${Math.random().toString(36).substr(2, 5)}`,
-                        text: m.text,
-                        rect: (0, screenScale_1.toDriverRect)({ x: m.x0, y: m.y0, width: m.x1 - m.x0, height: m.y1 - m.y0 }, scale),
-                        confidence: m.confidence / 100,
-                    };
-                    this.virtualElementStore.set(el.id, el);
-                    return el;
-                });
+                return matches.map((m) => ({
+                    id: `omni_ocr_${Date.now()}_${Math.random().toString(36).substr(2, 5)}`,
+                    text: m.text,
+                    rect: (0, screenScale_1.toDriverRect)({ x: m.x0, y: m.y0, width: m.x1 - m.x0, height: m.y1 - m.y0 }, scale),
+                    confidence: m.confidence / 100,
+                }));
             }
             catch (err) {
                 this.logger.error(`OCR proactive search failed: ${err.message}`);
@@ -443,13 +435,11 @@ let OmniVisionService = OmniVisionService_1 = class OmniVisionService {
                     // The AI answers in the screenshot's pixels; the rect is the driver's
                     // (points on iOS), like a real element's.
                     const scale = yield (0, screenScale_1.screenScaleOf)(driver, screenshot);
-                    const el = {
-                        id: `omni_ai_${Date.now()}`,
+                    return {
+                        id: `omni_ai_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`,
                         rect: (0, screenScale_1.toDriverRect)({ x: coordinates.x - 20, y: coordinates.y - 20, width: 40, height: 40 }, scale),
                         confidence: 0.85,
                     };
-                    this.virtualElementStore.set(el.id, el);
-                    return el;
                 }
             }
             catch (err) {
@@ -505,11 +495,48 @@ let OmniVisionService = OmniVisionService_1 = class OmniVisionService {
             }
         });
     }
-    addVirtualElement(element) {
-        this.virtualElementStore.set(element.id, element);
+    /**
+     * Keep `element` for `sessionId`, whose test was handed its id (a
+     * `-custom:ai-*` find, a heal), until the session ends (`forgetSession`)
+     * or the limits push it out. A find doesn't keep what it finds: device
+     * control's locator test only shows the ids, and a tap uses its element at
+     * once.
+     */
+    remember(sessionId, element) {
+        this.drop(element.id);
+        this.elements.set(element.id, { element, sessionId });
+        let ids = this.bySession.get(sessionId);
+        if (!ids) {
+            ids = new Set();
+            this.bySession.set(sessionId, ids);
+        }
+        ids.add(element.id);
+        if (ids.size > exports.MAX_VIRTUAL_ELEMENTS_PER_SESSION)
+            this.drop(ids.values().next().value);
+        if (this.elements.size > exports.MAX_VIRTUAL_ELEMENTS)
+            this.drop(this.elements.keys().next().value);
+    }
+    /** The element, when `sessionId` found it and still has it. */
+    getVirtualElement(id, sessionId) {
+        const held = this.elements.get(id);
+        return held && held.sessionId === sessionId ? held.element : undefined;
+    }
+    /** Drop every element a session found: it has ended (sessionMemory.ts). */
+    forgetSession(sessionId) {
+        var _a;
+        for (const id of (_a = this.bySession.get(sessionId)) !== null && _a !== void 0 ? _a : [])
+            this.elements.delete(id);
+        this.bySession.delete(sessionId);
     }
-    getVirtualElement(id) {
-        return this.virtualElementStore.get(id);
+    drop(id) {
+        const held = this.elements.get(id);
+        if (!held)
+            return;
+        this.elements.delete(id);
+        const ids = this.bySession.get(held.sessionId);
+        ids === null || ids === void 0 ? void 0 : ids.delete(id);
+        if (ids && ids.size === 0)
+            this.bySession.delete(held.sessionId);
     }
     /**
      * Omni-Click: Find a target by OCR text and click its center using W3C actions.

package/lib/src/services/passwordResetLink.js

@@ -1,25 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetLinkBase = resetLinkBase;
 exports.buildResetLink = buildResetLink;
+exports.requestBase = requestBase;
+exports.describeLifetime = describeLifetime;
 exports.resetEmail = resetEmail;
+const config_1 = require("../config");
+const publicUrl_1 = require("./publicUrl");
 /**
- * The URL a reset token is redeemed at. Built from the request so it matches
- * the host the caller reached the server on (honouring a TLS-terminating
- * proxy's x-forwarded-proto). The raw token is a credential for the account
- * until it expires or is used: never log the result.
+ * Where a password reset link points, and the email that carries it. The raw
+ * token in a link is a credential for the account until it expires or is
+ * used: never log the result.
  *
  * The token goes in the fragment (#), not the path. Browsers never send the
  * fragment to the server, so opening the link can't put the token in any
  * server-side log. As a path segment it was logged on every open: Appium's
  * [HTTP] request line and Xenon's UI-fallback line both record the URL.
  */
-function buildResetLink(req, rawToken) {
+/**
+ * The address a link Xenon sends (by email, or to the log fallback) points
+ * at: this server's address from XENON_PUBLIC_URL (publicServerBase), or
+ * null when it is unset or not a usable address.
+ *
+ * Never the request's Host header. Through 2.14 the link was built from it,
+ * so anyone could ask for a reset of someone else's account naming a host of
+ * their own (a matching Origin passes the CSRF check), and Xenon emailed the
+ * victim a genuine link to that host, which handed over the token.
+ */
+function resetLinkBase(cfg = config_1.config) {
+    return (0, publicUrl_1.publicServerBase)(cfg);
+}
+/** The reset page for `rawToken`, under `base` (resetLinkBase, or requestBase). */
+function buildResetLink(base, rawToken) {
+    return `${base}/xenon/reset-password#${rawToken}`;
+}
+/**
+ * The address the caller reached this server on, honouring a TLS-terminating
+ * proxy's x-forwarded-proto. Only for a link handed back to the signed-in
+ * administrator who asked for it (POST /users/:id/reset-link when it can't be
+ * emailed): they see where it points before passing it on, and hold the token
+ * anyway. Never for a link Xenon sends to someone else.
+ */
+function requestBase(req) {
     const proto = req.secure || req.headers['x-forwarded-proto'] === 'https' ? 'https' : 'http';
     const host = req.headers.host || 'localhost';
-    return `${proto}://${host}/xenon/reset-password#${rawToken}`;
+    return `${proto}://${host}`;
+}
+/** "1 hour", "30 minutes", "2 hours": a reset link's lifetime, for the email. */
+function describeLifetime(ms) {
+    const minutes = Math.max(1, Math.round(ms / 60000));
+    if (minutes % 60 === 0) {
+        const hours = minutes / 60;
+        return `${hours} hour${hours === 1 ? '' : 's'}`;
+    }
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
 }
-/** The reset email, shared by self-service and admin-issued resets. */
-function resetEmail(user, link) {
+/**
+ * The reset email, shared by self-service and admin-issued resets. `ttlMs` is
+ * how long the link lasts (PasswordResetService.ttlMs(), from
+ * XENON_RESET_TOKEN_TTL_MS): the email said "1 hour" whatever it was.
+ */
+function resetEmail(user, link, ttlMs) {
     return {
         to: user.email,
         subject: 'Reset your Xenon password',
@@ -27,6 +68,6 @@ function resetEmail(user, link) {
             `Someone requested a password reset for your Xenon account. ` +
             `If that was you, click the link below to choose a new password:\n\n` +
             `${link}\n\n` +
-            `This link expires in 1 hour. If you did not request this, ignore this email — no action is needed.\n`,
+            `This link expires in ${describeLifetime(ttlMs)}. If you did not request this, ignore this email — no action is needed.\n`,
     };
 }

package/lib/src/services/passwordResetMode.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.passwordResetMode = passwordResetMode;
+const passwordResetLink_1 = require("./passwordResetLink");
 function passwordResetMode(cfg) {
-    return cfg.smtpUrl && cfg.smtpUrl.trim() ? 'email' : 'admin';
+    const smtp = !!(cfg.smtpUrl && cfg.smtpUrl.trim());
+    return smtp && (0, passwordResetLink_1.resetLinkBase)(cfg) !== null ? 'email' : 'admin';
 }

package/lib/src/services/publicUrl.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publicServerBase = publicServerBase;
+const config_1 = require("../config");
+/**
+ * XENON_PUBLIC_URL: the address people reach this Xenon server at, such as
+ * https://xenon.example.com or http://lab-mac:4723. Links Xenon hands out
+ * (password reset links, a device's dashboard_link) are built from it, never
+ * from the request's Host header, which whoever sends the request chooses.
+ *
+ * The dashboard's own address is taken too: a trailing `/xenon` or `/xenon/`
+ * is dropped, so `http://localhost:4723/xenon/` gives `http://localhost:4723`.
+ * Kept as given it built `/xenon/xenon/reset-password`, which the dashboard
+ * sends to its sign-in page, losing the token.
+ *
+ * Any other path is refused: the dashboard loads its pages, scripts and API
+ * from `/xenon` on the server's root (its base path is fixed at build time),
+ * so it can't be served under a reverse-proxy prefix, and a link under one
+ * wouldn't open. So are an address that isn't http(s), and one with a query,
+ * fragment or user name (a fragment would swallow a reset token).
+ *
+ * Returns the origin (scheme, host and port, no trailing slash), or null when
+ * the variable is unset or not such an address.
+ */
+function publicServerBase(cfg = config_1.config) {
+    var _a;
+    const raw = (_a = cfg.publicUrl) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!raw)
+        return null;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch (_b) {
+        return null;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return null;
+    if (url.search || url.hash || url.username || url.password)
+        return null;
+    const path = url.pathname.replace(/\/+$/, '');
+    if (path !== '' && path !== '/xenon')
+        return null;
+    return url.origin;
+}

package/lib/src/services/session/sessionIdentity.js

@@ -21,9 +21,11 @@ function resolveSessionIdentity(input) {
         if (!input.sessionToken)
             return NONE;
         // Attribution is decoupled from enforcement: a token that does not verify is
-        // IGNORED here, never rejected. assertSessionTokenGate remains the only
-        // decider of whether the session is admitted. That separation is what lets a
-        // valid token identify its caller even when the gate is switched off.
+        // IGNORED here, never rejected. Whether the session is admitted is decided
+        // by the caller: assertSessionTokenGate for a session with no valid
+        // credentials, and authorizeSessionRequest's `sessions` scope check for a
+        // token that verifies. That separation is what lets a valid token identify
+        // its caller even when the gate is switched off.
         try {
             const payload = yield input.verify(input.sessionToken);
             const sub = payload === null || payload === void 0 ? void 0 : payload.sub;

package/lib/src/services/session/shutdownReason.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNEXPECTED_SHUTDOWN_REASON = void 0;
+exports.unexpectedShutdownReason = unexpectedShutdownReason;
+/** The reason recorded when Appium ends a session and gives no cause of its own. */
+exports.UNEXPECTED_SHUTDOWN_REASON = 'Driver shut down unexpectedly';
+/**
+ * The failure reason of a session Appium ended by itself
+ * (`XenonPlugin.onUnexpectedShutdown`): the message of the cause Appium
+ * passed, else UNEXPECTED_SHUTDOWN_REASON.
+ *
+ * Appium's new-command timeout is the usual cause, and its message ("New
+ * Command Timeout of 60 seconds expired. Try customizing the timeout using
+ * the 'newCommandTimeout' desired capability") is what files the session
+ * under TIMEOUT. A driver that gives up on itself passes its own error, such
+ * as base-driver's "The driver was unexpectedly shut down!". The umbrella's
+ * placeholder for a missing cause, "Unknown error", says nothing, so it gets
+ * the fallback too. Through 2.14 every such session was recorded with the
+ * fixed reason, which no failure pattern matches, so an idle session was
+ * filed UNKNOWN.
+ */
+function unexpectedShutdownReason(cause) {
+    const message = typeof cause === 'string' ? cause : cause === null || cause === void 0 ? void 0 : cause.message;
+    const text = typeof message === 'string' ? message.trim() : '';
+    return text && text !== 'Unknown error' ? text : exports.UNEXPECTED_SHUTDOWN_REASON;
+}

package/lib/src/services/settings/aiEngineSettings.js

@@ -0,0 +1,219 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.AiEngineSettings = exports.AI_ENGINE_SETTINGS = exports.AI_PROVIDERS = void 0;
+exports.pickAiEngine = pickAiEngine;
+exports.effectiveAiEngine = effectiveAiEngine;
+exports.validateAiEngineUpdate = validateAiEngineUpdate;
+exports.aiEngineUpdateOf = aiEngineUpdateOf;
+const typedi_1 = require("typedi");
+const logger_1 = __importDefault(require("../../logger"));
+const config_1 = require("../../config");
+const web_config_service_1 = require("../../data-service/web-config-service");
+/**
+ * The AI engine page's settings: which provider answers the AI calls (failure
+ * analysis, the visual and LLM healing tiers, visual assertions), and the model
+ * and address it uses.
+ *
+ * They follow the rule every lab setting does (labSettings.ts): a value saved
+ * in the dashboard (`WebConfig`, written by `POST /config`), else the plugin
+ * option or environment variable the server was started with, else the
+ * default. The result is written to `config`, which every AI call reads, at
+ * boot and on each save, so a change applies to the next call without a
+ * restart. Through 2.14 `POST /config` changed `config` and saved nothing: a
+ * restart went back to the provider the server was started with.
+ *
+ * API keys are not among them. They come from the server's environment only,
+ * are never saved, and are never sent to the dashboard.
+ */
+exports.AI_PROVIDERS = ['gemini', 'openai', 'anthropic', 'ollama'];
+/** The settings decided here, by their names in `config`, `WebConfig` and `/config`. */
+exports.AI_ENGINE_SETTINGS = [
+    'aiProvider',
+    'aiModel',
+    'aiBaseUrl',
+    'geminiModel',
+    'openaiModel',
+    'anthropicModel',
+    'ollamaModel',
+];
+const MODEL_SETTINGS = [
+    'aiModel',
+    'geminiModel',
+    'openaiModel',
+    'anthropicModel',
+    'ollamaModel',
+];
+const DEFAULT_PROVIDER = 'gemini';
+const MODEL_MAX_LENGTH = 200;
+const BASE_URL_MAX_LENGTH = 2048;
+const isProvider = (v) => typeof v === 'string' && exports.AI_PROVIDERS.includes(v);
+const isNonEmpty = (v) => typeof v === 'string' && v.trim() !== '';
+/** The AI engine settings in `source` (the running config, the saved rows), and nothing else. */
+function pickAiEngine(source) {
+    const out = {};
+    for (const name of exports.AI_ENGINE_SETTINGS) {
+        if (typeof source[name] === 'string')
+            out[name] = source[name];
+    }
+    return out;
+}
+/**
+ * The settings in effect, field by field: the saved value when it can work,
+ * else the one the server was started with, else the default (gemini; a model
+ * or base URL has none, and the provider's own then applies). An empty saved
+ * value is the person clearing it. The started-with provider is kept as it
+ * is, even one Xenon doesn't know: falling back to another provider would
+ * send screenshots somewhere the server's owner didn't choose. AIService then
+ * runs with no provider, and says so.
+ */
+function effectiveAiEngine(startup, saved) {
+    const out = {
+        aiProvider: isProvider(saved.aiProvider)
+            ? saved.aiProvider
+            : isNonEmpty(startup.aiProvider)
+                ? startup.aiProvider
+                : DEFAULT_PROVIDER,
+    };
+    for (const name of exports.AI_ENGINE_SETTINGS) {
+        if (name === 'aiProvider')
+            continue;
+        const mine = saved[name];
+        out[name] = isNonEmpty(mine)
+            ? mine.trim()
+            : isNonEmpty(startup[name])
+                ? startup[name]
+                : undefined;
+    }
+    return out;
+}
+/** Why `url` can't be saved as the base URL, or null. */
+function baseUrlProblem(url) {
+    const why = "aiBaseUrl must be an http or https address with no user name, password or query (the API key comes from the server's environment), or empty to use the server's own.";
+    if (url.length > BASE_URL_MAX_LENGTH)
+        return why;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (_a) {
+        return why;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return why;
+    // Anything that could carry a credential would be one saved in the database.
+    if (parsed.username || parsed.password || parsed.search || parsed.hash)
+        return why;
+    return null;
+}
+/**
+ * What is wrong with the AI engine fields of a settings update, or null.
+ * Checked before anything is saved: a saved value outlives the restart that
+ * used to undo it. Each may be empty, to go back to what the server was
+ * started with. Fields not sent are not checked.
+ */
+function validateAiEngineUpdate(body) {
+    const has = (key) => body[key] !== undefined;
+    if (has('aiProvider') && !(body.aiProvider === '' || isProvider(body.aiProvider))) {
+        return {
+            field: 'aiProvider',
+            message: `aiProvider must be one of ${exports.AI_PROVIDERS.join(', ')}, or empty to use the server's own.`,
+        };
+    }
+    for (const field of MODEL_SETTINGS) {
+        if (!has(field))
+            continue;
+        const value = body[field];
+        const name = typeof value === 'string' ? value.trim() : null;
+        if (name === null || name.length > MODEL_MAX_LENGTH || /[\s\u0000-\u001f\u007f]/.test(name)) {
+            return {
+                field,
+                message: `${field} must be a model name with no spaces, of at most ${MODEL_MAX_LENGTH} characters, or empty to use the server's own.`,
+            };
+        }
+    }
+    if (has('aiBaseUrl')) {
+        const value = body.aiBaseUrl;
+        const problem = typeof value !== 'string'
+            ? 'aiBaseUrl must be text.'
+            : value.trim() === ''
+                ? null
+                : baseUrlProblem(value.trim());
+        if (problem)
+            return { field: 'aiBaseUrl', message: problem };
+    }
+    return null;
+}
+/** The AI engine fields of a checked update, as they are saved: names trimmed. */
+function aiEngineUpdateOf(body) {
+    const picked = pickAiEngine(body);
+    for (const name of Object.keys(picked))
+        picked[name] = picked[name].trim();
+    return picked;
+}
+/**
+ * Keeps `config`'s AI engine settings at the values in effect. Loaded once at
+ * boot, after the startup options were applied and the database is ready, and
+ * told of each save by `POST /config`.
+ */
+let AiEngineSettings = class AiEngineSettings {
+    constructor() {
+        /** What the dashboard saved. */
+        this.saved = {};
+    }
+    /**
+     * Reads the saved settings and applies them. A database that can't be read
+     * leaves the startup settings in charge, as it does for the other settings.
+     */
+    load() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.startedWith();
+            try {
+                this.saved = pickAiEngine((yield typedi_1.Container.get(web_config_service_1.WebConfigService).getConfig()));
+            }
+            catch (err) {
+                this.saved = {};
+                logger_1.default.warn(`Could not read the saved AI engine settings, using the startup options: ${err === null || err === void 0 ? void 0 : err.message}`);
+            }
+            this.apply();
+        });
+    }
+    /** What `POST /config` just saved, in force for the next AI call. */
+    noteSaved(update) {
+        this.startedWith();
+        this.saved = Object.assign(Object.assign({}, this.saved), update);
+        this.apply();
+    }
+    startedWith() {
+        if (!this.startup)
+            this.startup = pickAiEngine(config_1.config);
+        return this.startup;
+    }
+    apply() {
+        const before = config_1.config.aiProvider;
+        (0, config_1.updateConfig)(effectiveAiEngine(this.startedWith(), this.saved));
+        if (config_1.config.aiProvider !== before)
+            logger_1.default.info(`AI provider: ${config_1.config.aiProvider}`);
+    }
+};
+exports.AiEngineSettings = AiEngineSettings;
+exports.AiEngineSettings = AiEngineSettings = __decorate([
+    (0, typedi_1.Service)()
+], AiEngineSettings);

package/lib/src/services/token/mintedLifetime.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Nothing a credential mints outlives it.
+ *
+ * `credentialExpiresAt` is req.auth.credentialExpiresAt: when the credential
+ * making the request stops working (a Bearer token's `exp`, an API key's
+ * `expiresAt`), as epoch ms, or undefined for one that doesn't expire (a key
+ * without an expiry, a dashboard sign-in, which renews itself).
+ *
+ * Through 2.14 a 1-hour Bearer token could make itself an API key that never
+ * expired (POST /profile/tokens, POST /apikeys), or mint a fresh 1-hour token
+ * before it expired, and so on for ever (POST /auth/token).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mintedLifetimeSec = mintedLifetimeSec;
+exports.keyExpiryWithin = keyExpiryWithin;
+/**
+ * A minted token's lifetime in seconds: `defaultSec`, cut to what is left of
+ * the credential minting it, less a second so the minted token's `exp`
+ * can't round past it. Throws when nothing is left.
+ */
+function mintedLifetimeSec(defaultSec, credentialExpiresAt) {
+    if (credentialExpiresAt === undefined)
+        return defaultSec;
+    const left = Math.floor((credentialExpiresAt - Date.now()) / 1000) - 1;
+    if (left < 1)
+        throw new Error('the credential used to mint this token has expired');
+    return Math.min(defaultSec, left);
+}
+/**
+ * An API key's expiry, made with a credential that may itself expire: the
+ * expiry asked for, or the credential's when none was asked for; an error
+ * when the one asked for is later than the credential's, or the credential
+ * has already expired.
+ */
+function keyExpiryWithin(requested, credentialExpiresAt) {
+    if (credentialExpiresAt === undefined)
+        return { expiresAt: requested };
+    // Token verification allows 60 s of clock skew, so a request can arrive on
+    // a credential just past its exp: it must not make a key already expired.
+    if (credentialExpiresAt <= Date.now()) {
+        return { error: 'the credential you are using has expired' };
+    }
+    if (requested && requested.getTime() > credentialExpiresAt) {
+        return {
+            error: 'expiresAt can be no later than the credential you are using, which expires at ' +
+                new Date(credentialExpiresAt).toISOString(),
+        };
+    }
+    return { expiresAt: requested !== null && requested !== void 0 ? requested : new Date(credentialExpiresAt) };
+}