@xenon-device-management/xenon 1.2.0 → 1.3.0

package/lib/schema.json

@@ -10,7 +10,8 @@
                 "android",
                 "both"
             ],
-            "default": "both"
+            "default": "both",
+            "description": "Which mobile platform(s) Xenon should discover and orchestrate."
         },
         "androidDeviceType": {
             "title": "DeviceTypeToInclude",
@@ -20,14 +21,16 @@
                 "real",
                 "simulated"
             ],
-            "default": "both"
+            "default": "both",
+            "description": "Which Android device kinds to include: physical devices, emulators, or both."
         },
         "simulators": {
             "type": "array",
             "items": {
                 "$ref": "#/definitions/SimulatorConfig"
             },
-            "default": []
+            "default": [],
+            "description": "Allow-list of iOS simulators (by name + sdk) to expose. Empty array means expose all discoverable simulators."
         },
         "iosDeviceType": {
             "title": "DeviceTypeToInclude1",
@@ -37,28 +40,34 @@
                 "real",
                 "simulated"
             ],
-            "default": "both"
+            "default": "both",
+            "description": "Which iOS device kinds to include: physical devices, simulators, or both."
         },
         "hub": {
-            "type": "string"
+            "type": "string",
+            "description": "URL of the Xenon hub this instance should register with as a node (e.g. http://hub.example:4723). Omit to run as a standalone hub."
         },
         "remoteMachineProxyIP": {
-            "type": "string"
+            "type": "string",
+            "description": "Public host/URL that clients should use to reach this node when running behind a reverse proxy or NAT."
         },
         "adbRemote": {
             "type": "array",
             "items": {
                 "type": "string"
             },
-            "default": []
+            "default": [],
+            "description": "List of remote ADB hosts in host:port form (e.g. '192.168.1.50:5037') to discover Android devices on other machines."
         },
         "skipChromeDownload": {
             "type": "boolean",
-            "default": true
+            "default": true,
+            "description": "Skip the automatic ChromeDriver download performed by uiautomator2. Leave true unless you specifically need Xenon to manage Chrome binaries."
         },
         "maxSessions": {
             "type": "number",
-            "default": 8
+            "default": 8,
+            "description": "Maximum number of Appium sessions this node will run concurrently. Additional requests queue until a slot frees."
         },
         "cloud": {
             "type": "object",
@@ -77,7 +86,8 @@
             "items": {
                 "$ref": "#/definitions/EmulatorConfig"
             },
-            "default": []
+            "default": [],
+            "description": "Allow-list of Android emulator AVDs to expose. Empty array means expose all discoverable emulators."
         },
         "proxy": {
             "type": "object",
@@ -85,64 +95,79 @@
         },
         "deviceAvailabilityTimeoutMs": {
             "type": "number",
-            "default": 300000
+            "default": 300000,
+            "description": "How long (ms) a session request waits for a free device before failing."
         },
         "deviceAvailabilityQueryIntervalMs": {
             "type": "number",
-            "default": 10000
+            "default": 10000,
+            "description": "How often (ms) the session queue polls for a free device while waiting."
         },
         "sendNodeDevicesToHubIntervalMs": {
             "type": "number",
-            "default": 30000
+            "default": 30000,
+            "description": "How often (ms) a node pushes its current device list to the hub. Only used when `hub` is set."
         },
         "checkStaleDevicesIntervalMs": {
             "type": "number",
-            "default": 30000
+            "default": 30000,
+            "description": "How often (ms) the hub prunes devices from nodes that have stopped heartbeating."
         },
         "checkBlockedDevicesIntervalMs": {
             "type": "number",
-            "default": 30000
+            "default": 30000,
+            "description": "How often (ms) to re-evaluate manually-blocked devices and the session reconciler that frees orphaned busy devices."
         },
         "newCommandTimeoutSec": {
             "type": "number",
-            "default": 60
+            "default": 60,
+            "description": "Default Appium newCommandTimeout (seconds) applied when a client does not send one. Also drives the reconciler that releases devices idle past this threshold."
         },
         "bindHostOrIp": {
             "type": "string",
-            "default": "127.0.0.1"
+            "default": "127.0.0.1",
+            "description": "Host/IP the Xenon REST and WebSocket server binds to. Set to 0.0.0.0 to expose on all interfaces."
         },
         "enableDashboard": {
             "type": "boolean",
-            "default": false
+            "default": false,
+            "description": "Serve the React dashboard at /xenon/ and the Socket.io event stream."
         },
         "bootedSimulators": {
             "type": "boolean",
-            "default": false
+            "default": false,
+            "description": "Only discover iOS simulators that are already booted. Recommended on machines with many installed simulators — avoids allocating WDA/MJPEG ports for shutdown sims (the WDA pool is 8100-8199, 100 ports)."
         },
         "bootedEmulators": {
             "type": "boolean",
-            "default": false
+            "default": false,
+            "description": "Only discover Android emulators that are already booted."
         },
         "removeDevicesFromDatabaseBeforeRunningThePlugin": {
             "type": "boolean",
-            "default": false
+            "default": false,
+            "description": "Wipe the persisted Device table at startup so discovery begins from a clean slate. Useful after hardware changes."
         },
         "healthCheckIntervalMs": {
             "type": "number",
-            "default": 86400000
+            "default": 86400000,
+            "description": "Default interval (ms) between background device health checks. Overridden when `healthCheckSchedule` is set."
         },
         "healthCheckSchedule": {
-            "type": "string"
+            "type": "string",
+            "description": "Cron expression for the device health-check job (e.g. '0 * * * *' for hourly). When set, takes precedence over `healthCheckIntervalMs`."
         },
         "databaseProvider": {
             "type": "string",
             "enum": [
                 "sqlite",
                 "postgresql"
-            ]
+            ],
+            "description": "Database backend. Defaults to sqlite (file under ~/.cache/xenon). Use postgresql for multi-node hub deployments."
         },
         "databaseUrl": {
-            "type": "string"
+            "type": "string",
+            "description": "Prisma-style database URL. For sqlite: `file:/path/to/xenon.db`. For postgres: `postgresql://user:pass@host/db`. Falls back to the DATABASE_URL env var."
         },
         "aiProvider": {
             "type": "string",
@@ -151,55 +176,77 @@
                 "openai",
                 "anthropic",
                 "ollama"
-            ]
+            ],
+            "description": "AI provider for the LLM healing tier and visual analysis. Also controlled by XENON_AI_PROVIDER."
         },
         "aiModel": {
-            "type": "string"
+            "type": "string",
+            "description": "Override the default model for the selected `aiProvider` (e.g. 'gemini-1.5-pro', 'gpt-4o', 'claude-sonnet-4-6'). Falls back to XENON_AI_MODEL."
         },
         "aiBaseUrl": {
-            "type": "string"
+            "type": "string",
+            "description": "Custom base URL for the AI provider (e.g. a local Ollama server or an OpenAI-compatible gateway). Falls back to XENON_AI_BASE_URL."
         },
         "geminiApiKey": {
-            "type": "string"
+            "type": "string",
+            "description": "Gemini API key. Prefer setting XENON_GEMINI_API_KEY (or GEMINI_API_KEY) via environment instead of committing it to a config file."
         },
         "openaiApiKey": {
-            "type": "string"
+            "type": "string",
+            "description": "OpenAI API key. Prefer setting XENON_OPENAI_API_KEY (or OPENAI_API_KEY) via environment."
         },
         "anthropicApiKey": {
-            "type": "string"
+            "type": "string",
+            "description": "Anthropic API key. Prefer setting XENON_ANTHROPIC_API_KEY (or ANTHROPIC_API_KEY) via environment."
         },
         "enableSelfHealing": {
             "type": "boolean",
-            "default": true
+            "default": true,
+            "description": "Enable the 5-tier self-healing pipeline (Native → Fuzzy XML → OCR → Visual AI → LLM) for failed findElement calls. Can also be toggled at runtime from the dashboard."
         },
         "buildCleanupDays": {
             "type": "number",
-            "default": 30
+            "default": 30,
+            "description": "Builds/sessions older than this many days are purged by the cleanup job."
         },
         "buildCleanupMaxCount": {
             "type": "number",
-            "default": 100
+            "default": 100,
+            "description": "Maximum number of builds to retain. Oldest-first eviction beyond this cap regardless of `buildCleanupDays`."
         },
         "buildCleanupSchedule": {
             "type": "string",
-            "default": "0 0 * * *"
+            "default": "0 0 * * *",
+            "description": "Cron expression for the retention job. Default '0 0 * * *' runs at midnight."
         },
         "deleteBuildAssets": {
             "type": "boolean",
-            "default": true
+            "default": true,
+            "description": "When true, the cleanup job also deletes session video recordings and screenshots from disk (not just DB rows)."
         },
         "sessionHeartbeatIntervalMs": {
             "type": "number",
-            "default": 30000
+            "default": 30000,
+            "description": "How often (ms) each active session writes a heartbeat. The orphan sweeper uses ~3× this interval to detect abandoned sessions."
         },
         "enableJsonLogging": {
             "type": "boolean",
-            "default": false
+            "default": false,
+            "description": "Emit structured JSON log lines instead of human-readable text. Recommended for shipping logs to a log aggregator."
         },
         "tlsRejectUnauthorized": {
             "type": "boolean",
             "default": true,
             "description": "Whether to verify TLS certificates for internal outgoing requests. Default is true. Set to false only for dev/test."
+        },
+        "authDisabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Disable API key authentication for all /xenon/api/* endpoints. Use only in local dev environments."
+        },
+        "nodeSecret": {
+            "type": "string",
+            "description": "Shared secret for hub-node channel authentication. Nodes must send this value in X-Xenon-Node-Secret header."
         }
     },
     "required": [

package/lib/src/InternalHttpClient.js

@@ -60,16 +60,31 @@ const logger_1 = __importDefault(require("./logger"));
  * - Correlation ID tracking
  */
 class InternalHttpClient {
-    constructor(tlsRejectUnauthorized) {
+    constructor(tlsRejectUnauthorized, timeoutMs) {
         this.axiosInstance = axios_1.default.create({
             httpAgent: this.getHttpAgent(),
             httpsAgent: this.getHttpsAgent(tlsRejectUnauthorized),
-            timeout: 30000,
+            timeout: InternalHttpClient.resolveTimeoutMs(timeoutMs),
             maxContentLength: Infinity,
             maxBodyLength: Infinity,
         });
         this.setupInterceptors();
     }
+    // Ops can shorten the global default via env var when a slow node is
+    // stalling session creation. Per-call override is still available via
+    // AxiosRequestConfig.timeout on individual post/get/etc calls.
+    static resolveTimeoutMs(explicit) {
+        if (typeof explicit === 'number' && explicit > 0)
+            return explicit;
+        const raw = process.env.XENON_HTTP_TIMEOUT_MS;
+        if (raw) {
+            const parsed = Number(raw);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+            logger_1.default.warn(`[HTTP] Ignoring invalid XENON_HTTP_TIMEOUT_MS=${raw}, using 30000ms default`);
+        }
+        return 30000;
+    }
     getHttpAgent() {
         return new http_1.default.Agent({
             keepAlive: true,
@@ -151,30 +166,55 @@ class InternalHttpClient {
             catch (e) {
                 /* ignore */
             }
-            if (!config || config.retryCount === undefined) {
+            if (!config) {
+                return Promise.reject(error);
+            }
+            if (config.retryCount === undefined) {
                 config.retryCount = 0;
             }
-            const maxRetries = 2;
             const status = response === null || response === void 0 ? void 0 : response.status;
             // Log failed request
             if (!(config === null || config === void 0 ? void 0 : config.silent)) {
                 logger_1.default.warn(`[HTTP ←] ${(_c = config === null || config === void 0 ? void 0 : config.method) === null || _c === void 0 ? void 0 : _c.toUpperCase()} ${config === null || config === void 0 ? void 0 : config.url} ` +
                     `[${status || 'ERR'}] ${duration}ms - ${error.message}`);
             }
-            // Don't retry client errors (4xx) except for occasional 429
-            if (status && status < 500 && status !== 429) {
+            const decision = InternalHttpClient.classifyRetry(error);
+            if (!decision.retryable || config.retryCount >= InternalHttpClient.MAX_RETRIES) {
                 return Promise.reject(error);
             }
-            if (config.retryCount < maxRetries) {
-                config.retryCount += 1;
-                const backoff = config.retryCount * 1000;
-                logger_1.default.warn(`[HTTP ↻] Retrying ${config.url} in ${backoff}ms (Attempt ${config.retryCount}/${maxRetries})...`);
-                yield new Promise((resolve) => setTimeout(resolve, backoff));
-                return this.axiosInstance(config);
-            }
-            return Promise.reject(error);
+            config.retryCount += 1;
+            const backoff = InternalHttpClient.computeBackoff(config.retryCount);
+            logger_1.default.warn(`[HTTP ↻] Retrying ${config.url} in ${backoff}ms (${decision.reason}, attempt ${config.retryCount}/${InternalHttpClient.MAX_RETRIES})`);
+            yield new Promise((resolve) => setTimeout(resolve, backoff));
+            return this.axiosInstance(config);
         }));
     }
+    static classifyRetry(error) {
+        const response = error.response;
+        if (response) {
+            const s = response.status;
+            if (s >= 500)
+                return { retryable: true, reason: `HTTP ${s}` };
+            if (s === 429)
+                return { retryable: true, reason: 'rate limited (429)' };
+            return { retryable: false, reason: `HTTP ${s}` };
+        }
+        // No response — network/transport error
+        const code = error.code || '';
+        if (InternalHttpClient.RETRYABLE_NETWORK_CODES.has(code)) {
+            return { retryable: true, reason: `network: ${code}` };
+        }
+        if (/timeout/i.test(error.message)) {
+            return { retryable: true, reason: 'request timeout' };
+        }
+        return { retryable: false, reason: code || error.message };
+    }
+    static computeBackoff(attempt) {
+        const base = Math.min(InternalHttpClient.BASE_RETRY_MS * Math.pow(2, attempt - 1), InternalHttpClient.MAX_RETRY_MS);
+        // 0-25% jitter to avoid thundering-herd on a recovering node
+        const jitter = Math.random() * base * 0.25;
+        return Math.floor(base + jitter);
+    }
     static getClient(tlsRejectUnauthorized) {
         if (tlsRejectUnauthorized !== undefined) {
             return new InternalHttpClient(tlsRejectUnauthorized).axiosInstance;
@@ -210,3 +250,18 @@ class InternalHttpClient {
     }
 }
 exports.InternalHttpClient = InternalHttpClient;
+// Transient network failures worth retrying. Stalled/restarting node ports
+// commonly surface as these codes; the node is usually back within seconds.
+InternalHttpClient.RETRYABLE_NETWORK_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EPIPE',
+    'ECONNABORTED',
+    'ERR_NETWORK',
+]);
+InternalHttpClient.MAX_RETRIES = 3;
+InternalHttpClient.BASE_RETRY_MS = 500;
+InternalHttpClient.MAX_RETRY_MS = 4000;

package/lib/src/app/index.js

@@ -53,9 +53,11 @@ const package_json_1 = __importDefault(require("../../package.json"));
 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 config_1 = require("../config");
-const logger_1 = __importStar(require("../logger"));
+const logger_1 = __importDefault(require("../logger"));
+const sessionContext_1 = require("../logging/sessionContext");
 const dashboard_1 = __importDefault(require("./routers/dashboard"));
 const grid_1 = __importDefault(require("./routers/grid"));
 const control_1 = __importDefault(require("./routers/control"));
@@ -63,14 +65,40 @@ const apps_1 = __importDefault(require("./routers/apps"));
 const webhook_1 = __importDefault(require("./routers/webhook"));
 const reservation_1 = __importDefault(require("./routers/reservation"));
 const config_2 = __importDefault(require("./routers/config"));
+const apikeys_1 = require("./routers/apikeys");
+const auth_1 = require("./routers/auth");
+const processes_1 = require("./routers/processes");
+const apiKeyMiddleware_1 = require("../middleware/apiKeyMiddleware");
+const rateLimitMiddleware_1 = require("../middleware/rateLimitMiddleware");
+const nodeSecretMiddleware_1 = require("../middleware/nodeSecretMiddleware");
+const csrfMiddleware_1 = require("../middleware/csrfMiddleware");
 const swagger_1 = require("./swagger");
 const typedi_1 = require("typedi");
 const dashboardPluginUrl = null;
 const ASYNC_LOCK = new async_lock_1.default();
 const router = express_1.default.Router(), apiRouter = express_1.default.Router(), staticFilesRouter = express_1.default.Router();
-router.use((0, cors_1.default)());
-apiRouter.use((0, cors_1.default)());
+// API is same-origin with the dashboard; block cross-origin browser callers.
+// Non-browser clients (curl, CLI, SDKs) send no Origin header and are unaffected.
+// Parent `router` has no cors() — if it did, its wildcard would leak through
+// to apiRouter responses because cors({origin:false}) below doesn't strip
+// headers set earlier in the chain. Static files keep permissive cors() so
+// the dashboard bundle can be embedded from anywhere if needed.
+apiRouter.use((0, cors_1.default)({ origin: false }));
 staticFilesRouter.use((0, cors_1.default)());
+// Tag every API request with an AsyncLocalStorage frame so downstream logs
+// (handlers, DB calls, outbound HTTP from InternalHttpClient) can attribute
+// themselves to this request/session without plumbing IDs through every call.
+// Regex picks up sessionId from /session/<id>/... paths so the context is
+// populated before the individual handler runs.
+const SESSION_ID_PATH_RE = /\/session\/([a-zA-Z0-9_-]{8,})(?:\/|$)/;
+apiRouter.use((req, res, next) => {
+    const inboundId = req.headers['x-request-id'] || '';
+    const requestId = inboundId || crypto_1.default.randomUUID();
+    const match = SESSION_ID_PATH_RE.exec(req.path);
+    const sessionId = match ? match[1] : undefined;
+    res.setHeader('X-Request-Id', requestId);
+    sessionContext_1.sessionContext.run({ requestId, sessionId }, () => next());
+});
 apiRouter.use((req, res, next) => {
     // Defensive Body Parsing Logic:
     // In some Appium versions, the global HTTP logger or other middleware drains the request stream
@@ -99,39 +127,39 @@ apiRouter.use((req, res, next) => {
     res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
     res.setHeader('Pragma', 'no-cache');
     res.setHeader('Expires', '0');
-    // Redact secrets from request body to prevent them from leaking into external logs
-    if (req.body && typeof req.body === 'object') {
-        req.body = (0, logger_1.redactSecrets)(req.body);
-    }
     next();
 });
-// Dashboard state cache - runs once and persists
+// 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) {
+    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 });
-                return response['pong'] ? `${req.protocol}://${req.get('host')}/dashboard` : '';
+                if (response && response['pong']) {
+                    dashboardRetryDelayMs = 1000;
+                    dashboardNextRetryAt = 0;
+                    return `${req.protocol}://${req.get('host')}/dashboard`;
+                }
             }
             catch (err) {
-                return '';
+                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'] = yield dashboardPluginPromise;
+    req['dashboard-plugin-url'] = dashboardPluginPromise ? yield dashboardPluginPromise : '';
     return next();
 }));
-apiRouter.get('/cliArgs', (req, res) => __awaiter(void 0, void 0, void 0, function* () {
-    res.json(yield (0, pluginArgs_1.getCLIArgs)());
-}));
-apiRouter.get('/metrics', (req, res) => __awaiter(void 0, void 0, void 0, function* () {
-    const { MetricsService } = yield Promise.resolve().then(() => __importStar(require('../services/MetricsService')));
-    const metrics = yield typedi_1.Container.get(MetricsService).getMetrics();
-    res.set('Content-Type', 'text/plain');
-    res.send(metrics);
-}));
 const findPublicPath = () => {
     const rootDir = path_1.default.resolve(__dirname, '..', '..');
     const searchPaths = [
@@ -156,10 +184,21 @@ const findPublicPath = () => {
 const publicPath = findPublicPath();
 logger_1.default.info(`[Xenon] Dashboard assets path: ${publicPath}`);
 logger_1.default.info(`[Xenon] Dashboard available at: /xenon/ (e.g. http://localhost:4723/xenon/)`);
-// Principal Security: Add permissive CSP and CORS for the dashboard
+// CSP for the dashboard. Keeps 'unsafe-inline' (React/Vite inline styles),
+// drops 'unsafe-eval' and the default-src wildcard to avoid full XSS-to-RCE.
+// Google Fonts (fonts.googleapis.com for CSS, fonts.gstatic.com for woff2)
+// are explicitly allowlisted because the bundled stylesheets @import them.
 router.use((req, res, next) => {
-    res.setHeader('Content-Security-Policy', "default-src * 'unsafe-inline' 'unsafe-eval' data: blob:; frame-ancestors 'self';");
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Content-Security-Policy', [
+        "default-src 'self'",
+        "script-src 'self' 'unsafe-inline'",
+        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+        "img-src 'self' data: blob:",
+        "media-src 'self' blob:",
+        "connect-src 'self' ws: wss: http: https:",
+        "font-src 'self' data: https://fonts.gstatic.com",
+        "frame-ancestors 'self'",
+    ].join('; ') + ';');
     next();
 });
 staticFilesRouter.use(express_1.default.static(publicPath, { index: false }));
@@ -168,6 +207,35 @@ router.use('/api', apiRouter);
 router.use('/session-recordings', express_1.default.static(config_1.config.sessionAssetsPath));
 router.use(staticFilesRouter);
 function createRouter(pluginArgs) {
+    // 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
+    // POST/PUT/DELETE/PATCH whose Origin/Referer doesn't match our Host.
+    apiRouter.use(csrfMiddleware_1.csrfMiddleware);
+    // Health endpoint: no auth, no rate limit
+    apiRouter.get('/health', (_req, res) => res.json({ ok: true }));
+    // Hub-node channel: node-secret auth instead of API key
+    apiRouter.use(['/register', '/unblock'], (0, nodeSecretMiddleware_1.nodeSecretMiddleware)(pluginArgs.nodeSecret || process.env.XENON_NODE_SECRET));
+    // Dashboard login: unauthenticated (rate-limited internally via separate IP logic)
+    apiRouter.use('/auth', (0, auth_1.authRouter)());
+    // All remaining /api/* requires API key + rate limit
+    apiRouter.use(apiKeyMiddleware_1.apiKeyMiddleware);
+    apiRouter.use((0, rateLimitMiddleware_1.rateLimitMiddleware)());
+    // Admin: API key management
+    apiRouter.use('/apikeys', (0, apikeys_1.apiKeysRouter)());
+    // Admin: running process snapshot (ops debugging)
+    apiRouter.use('/processes', (0, processes_1.processesRouter)());
+    // Exposes plugin CLI args (may include host, hub URL, etc.) — auth-gated.
+    apiRouter.get('/cliArgs', (_req, res) => __awaiter(this, void 0, void 0, function* () {
+        res.json(yield (0, pluginArgs_1.getCLIArgs)());
+    }));
+    // Prometheus-style metrics — auth-gated to avoid operational recon.
+    apiRouter.get('/metrics', (_req, res) => __awaiter(this, void 0, void 0, function* () {
+        const { MetricsService } = yield Promise.resolve().then(() => __importStar(require('../services/MetricsService')));
+        const metrics = yield typedi_1.Container.get(MetricsService).getMetrics();
+        res.set('Content-Type', 'text/plain');
+        res.send(metrics);
+    }));
     dashboard_1.default.register(apiRouter);
     grid_1.default.register(apiRouter, pluginArgs);
     control_1.default.register(apiRouter);

package/lib/src/app/routers/apikeys.js

@@ -0,0 +1,33 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiKeysRouter = apiKeysRouter;
+const express_1 = require("express");
+const typedi_1 = require("typedi");
+const ApiKeyService_1 = require("../../services/ApiKeyService");
+const scopeGuard_1 = require("../../middleware/scopeGuard");
+function apiKeysRouter() {
+    const r = (0, express_1.Router)();
+    const svc = typedi_1.Container.get(ApiKeyService_1.ApiKeyService);
+    r.post('/', (0, scopeGuard_1.scopeGuard)(['admin']), (req, res) => __awaiter(this, void 0, void 0, function* () {
+        const { name, scopes, rateLimit } = req.body;
+        if (!name || !Array.isArray(scopes) || scopes.length === 0) {
+            return res.status(400).json({ error: 'name and scopes required' });
+        }
+        const { id, raw } = yield svc.create({ name, scopes, rateLimit });
+        res.json({ id, key: raw });
+    }));
+    r.delete('/:id', (0, scopeGuard_1.scopeGuard)(['admin']), (req, res) => __awaiter(this, void 0, void 0, function* () {
+        yield svc.revoke(req.params.id);
+        res.json({ ok: true });
+    }));
+    return r;
+}

package/lib/src/app/routers/apps.js

@@ -16,7 +16,11 @@ const express_1 = require("express");
 const app_service_1 = require("../../dashboard/services/app-service");
 const logger_1 = __importDefault(require("../../logger"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const scopeGuard_1 = require("../../middleware/scopeGuard");
 const router = (0, express_1.Router)();
+// Uploading an APK/IPA or deleting one from the fleet requires devices scope.
+// App listings stay readable to any authenticated key.
+router.use((0, scopeGuard_1.mutationScopeGuard)(['devices']));
 router.get('/', (req, res) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const apps = yield app_service_1.APP_SERVICE.getApps();

package/lib/src/app/routers/auth.js

@@ -0,0 +1,36 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authRouter = authRouter;
+const express_1 = require("express");
+const typedi_1 = require("typedi");
+const ApiKeyService_1 = require("../../services/ApiKeyService");
+function authRouter() {
+    const r = (0, express_1.Router)();
+    const svc = typedi_1.Container.get(ApiKeyService_1.ApiKeyService);
+    r.post('/dashboard-session', (req, res) => __awaiter(this, void 0, void 0, function* () {
+        const { apiKey } = req.body;
+        if (!apiKey)
+            return res.status(400).json({ error: 'apiKey required' });
+        const row = yield svc.verify(apiKey);
+        if (!row)
+            return res.status(401).json({ error: 'invalid key' });
+        const isSecure = req.secure || req.headers['x-forwarded-proto'] === 'https';
+        res.cookie('xenon_dashboard_session', apiKey, {
+            httpOnly: true,
+            secure: isSecure,
+            sameSite: 'strict',
+            maxAge: 24 * 60 * 60 * 1000,
+        });
+        res.json({ ok: true, scopes: row.scopes });
+    }));
+    return r;
+}