@xen-orchestra/rest-api 0.31.1 → 0.33.0

package/dist/vms/vm.controller.mjs

@@ -7,13 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Example, Get, Path, Post, Query, Request, Response, Route, Security, Tags, SuccessResponse, Body, Put, Delete, Middlewares, } from 'tsoa';
+import { Body, Delete, Example, Extension, Get, Middlewares, Patch, Path, Post, Put, Query, Request, Response, Route, Security, SuccessResponse, Tags, } from 'tsoa';
 import { json } from 'express';
 import { inject } from 'inversify';
 import { incorrectState, invalidParameters } from 'xo-common/api-errors.js';
 import { provide } from 'inversify-binding-decorators';
 import { PassThrough } from 'node:stream';
-import { acl } from '../middlewares/acl.middleware.mjs';
+import { SUPPORTED_ACTIONS_BY_RESOURCE } from '@xen-orchestra/acl';
+import { acl, actionsFromBody } from '../middlewares/acl.middleware.mjs';
 import { asynchronousActionResp, badRequestResp, createdResp, forbiddenOperationResp, incorrectStateResp, internalServerErrorResp, invalidParameters as invalidParametersResp, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
 import { BASE_URL } from '../index.mjs';
 import { limitAndFilterArray, NDJSON_CONTENT_TYPE } from '../helpers/utils.helper.mjs';
@@ -28,6 +29,11 @@ import { partialVmBackupJobs, vmBackupJobIds } from '../open-api/oa-examples/bac
 import { messageIds, partialMessages } from '../open-api/oa-examples/message.oa-example.mjs';
 import { Task } from '@vates/task';
 const IGNORED_VDIS_TAG = '[NOSNAP]';
+// `datasources` is managed through the dedicated `/vms/{id}/stats/data_source`
+// endpoints, not as a direct VM property, so it cannot be updated via PATCH /vms.
+const UPDATE_VM_ACTIONS = Object.keys(SUPPORTED_ACTIONS_BY_RESOURCE.vm.update)
+    .filter(action => action !== 'datasources')
+    .map(k => `update:${k}`);
 let VmController = class VmController extends XapiXoController {
     #vmService;
     #backupJobService;
@@ -74,6 +80,29 @@ let VmController = class VmController extends XapiXoController {
     getVm(id) {
         return this.getObject(id);
     }
+    /**
+     * Partial update of a VM. Only the fields present in the body are modified;
+     * everything else is left untouched.
+     *
+     * Operations are applied sequentially: if one fails, previously applied
+     * changes are not rolled back.
+     *
+     * Required privilege per field provided in the body:
+     * - resource: vm, action: update:<field> (e.g. update:nameLabel, update:cpus, ...)
+     *
+     * Special fields:
+     * - `xenStoreData` keys are automatically prefixed with `vm-data/` when missing
+     *
+     * @example id "f07ab729-c0e8-721c-45ec-f11276377030"
+     * @example body {
+     *    "nameLabel": "web-prod-01",
+     *    "nameDescription": "Production web frontend — managed by n8n",
+     *    "notes": "Docker containers: nginx, app-1, app-2"
+     * }
+     */
+    async updateVm(id, body) {
+        await this.#vmService.updateVm(id, body);
+    }
     /**
      * Required privilege:
      * - resource: vm, action: delete
@@ -631,6 +660,7 @@ let VmController = class VmController extends XapiXoController {
 __decorate([
     Example(vmIds),
     Example(partialVms),
+    Extension('x-mcp-exposure', 'allow'),
     Get(''),
     Security('*', ['acl']),
     __param(0, Request()),
@@ -641,6 +671,7 @@ __decorate([
     __param(5, Query())
 ], VmController.prototype, "getVms", null);
 __decorate([
+    Extension('x-mcp-exposure', 'deny'),
     Get('{id}.{format}'),
     Middlewares(acl({ resource: 'vm', action: 'export', objectId: 'params.id' })),
     SuccessResponse(200, 'Download started', 'application/octet-stream'),
@@ -654,6 +685,7 @@ __decorate([
 ], VmController.prototype, "exportVm", null);
 __decorate([
     Example(vm),
+    Extension('x-mcp-exposure', 'allow'),
     Get('{id}'),
     Middlewares(acl({ resource: 'vm', action: 'read', objectId: 'params.id' })),
     Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
@@ -661,6 +693,25 @@ __decorate([
     __param(0, Path())
 ], VmController.prototype, "getVm", null);
 __decorate([
+    Patch('{id}'),
+    Middlewares([
+        json(),
+        acl({
+            resource: 'vm',
+            actions: actionsFromBody(UPDATE_VM_ACTIONS),
+            objectId: 'params.id',
+        }),
+    ]),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(invalidParametersResp.status, invalidParametersResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Body())
+], VmController.prototype, "updateVm", null);
+__decorate([
+    Extension('x-mcp-exposure', 'confirm'),
     Delete('{id}'),
     Middlewares(acl({ resource: 'vm', action: 'delete', objectId: 'params.id' })),
     SuccessResponse(noContentResp.status, noContentResp.description),
@@ -671,6 +722,7 @@ __decorate([
 ], VmController.prototype, "deleteVm", null);
 __decorate([
     Example(vmStatsExample),
+    Extension('x-mcp-exposure', 'deny'),
     Get('{id}/stats'),
     Middlewares(acl({ resource: 'vm', action: 'read', objectId: 'params.id' })),
     Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
@@ -680,6 +732,7 @@ __decorate([
     __param(1, Query())
 ], VmController.prototype, "getVmStats", null);
 __decorate([
+    Extension('x-mcp-exposure', 'confirm'),
     Put('{id}/stats/data_source/{data_source}'),
     Middlewares(acl({ resource: 'vm', action: 'update:datasources', objectId: 'params.id' })),
     SuccessResponse(noContentResp.status, noContentResp.description),
@@ -690,6 +743,7 @@ __decorate([
     __param(1, Path('data_source'))
 ], VmController.prototype, "addDataSource", null);
 __decorate([
+    Extension('x-mcp-exposure', 'confirm'),
     Delete('{id}/stats/data_source/{data_source}'),
     Middlewares(acl({ resource: 'vm', action: 'update:datasources', objectId: 'params.id' })),
     SuccessResponse(noContentResp.status, noContentResp.description),
@@ -701,6 +755,7 @@ __decorate([
 ], VmController.prototype, "deleteDataSource", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/start'),
     Middlewares([
         json(),
@@ -720,6 +775,7 @@ __decorate([
 ], VmController.prototype, "startVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/clean_shutdown'),
     Middlewares(acl({ resource: 'vm', action: 'shutdown:clean', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -732,6 +788,7 @@ __decorate([
 ], VmController.prototype, "cleanShutdownVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/clean_reboot'),
     Middlewares(acl({ resource: 'vm', action: 'reboot:clean', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -743,6 +800,7 @@ __decorate([
 ], VmController.prototype, "cleanRebootVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/hard_shutdown'),
     Middlewares(acl({ resource: 'vm', action: 'shutdown:hard', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -755,6 +813,7 @@ __decorate([
 ], VmController.prototype, "hardShutdownVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/hard_reboot'),
     Middlewares(acl({ resource: 'vm', action: 'reboot:hard', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -767,6 +826,7 @@ __decorate([
 ], VmController.prototype, "hardRebootVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/pause'),
     Middlewares(acl({ resource: 'vm', action: 'pause', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -779,6 +839,7 @@ __decorate([
 ], VmController.prototype, "pauseVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/suspend'),
     Middlewares(acl({ resource: 'vm', action: 'suspend', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -791,6 +852,7 @@ __decorate([
 ], VmController.prototype, "suspendVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/resume'),
     Middlewares(acl({ resource: 'vm', action: 'resume', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -803,6 +865,7 @@ __decorate([
 ], VmController.prototype, "resumeVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/unpause'),
     Middlewares(acl({ resource: 'vm', action: 'unpause', objectId: 'params.id' })),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -815,6 +878,7 @@ __decorate([
 ], VmController.prototype, "unpauseVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/revert_snapshot'),
     Middlewares([
         json(),
@@ -839,6 +903,7 @@ __decorate([
 ], VmController.prototype, "revertSnapshotVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/snapshot'),
     Middlewares([json(), acl({ resource: 'vm', action: 'snapshot', objectId: 'params.id' })]),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -852,6 +917,7 @@ __decorate([
 ], VmController.prototype, "snapshotVm", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/clone'),
     Middlewares(json()),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
@@ -865,6 +931,7 @@ __decorate([
 ], VmController.prototype, "cloneVm", null);
 __decorate([
     Example(genericAlarmsExample),
+    Extension('x-mcp-exposure', 'allow'),
     Get('{id}/alarms'),
     Security('*', ['acl']),
     Tags('alarms'),
@@ -879,6 +946,7 @@ __decorate([
 ], VmController.prototype, "getVmAlarms", null);
 __decorate([
     Example(vmVdis),
+    Extension('x-mcp-exposure', 'allow'),
     Get('{id}/vdis'),
     Security('*', ['acl']),
     Tags('vdis'),
@@ -894,6 +962,7 @@ __decorate([
 __decorate([
     Example(vmBackupJobIds),
     Example(partialVmBackupJobs),
+    Extension('x-mcp-exposure', 'allow'),
     Get('{id}/backup-jobs'),
     Security('*', ['acl']),
     Tags('backup-jobs'),
@@ -909,6 +978,7 @@ __decorate([
 __decorate([
     Example(messageIds),
     Example(partialMessages),
+    Extension('x-mcp-exposure', 'allow'),
     Get('{id}/messages'),
     Security('*', ['acl']),
     Tags('messages'),
@@ -924,6 +994,7 @@ __decorate([
 __decorate([
     Example(taskIds),
     Example(partialTasks),
+    Extension('x-mcp-exposure', 'allow'),
     Get('{id}/tasks'),
     Security('*', ['acl']),
     Tags('tasks'),
@@ -937,6 +1008,7 @@ __decorate([
     __param(6, Query())
 ], VmController.prototype, "getVmTasks", null);
 __decorate([
+    Extension('x-mcp-exposure', 'confirm'),
     Put('{id}/tags/{tag}'),
     Middlewares(acl({ resource: 'vm', action: 'update:tags', objectId: 'params.id' })),
     SuccessResponse(noContentResp.status, noContentResp.description),
@@ -946,6 +1018,7 @@ __decorate([
     __param(1, Path())
 ], VmController.prototype, "putVmTag", null);
 __decorate([
+    Extension('x-mcp-exposure', 'confirm'),
     Delete('{id}/tags/{tag}'),
     Middlewares(acl({ resource: 'vm', action: 'update:tags', objectId: 'params.id' })),
     SuccessResponse(noContentResp.status, noContentResp.description),
@@ -956,6 +1029,7 @@ __decorate([
 ], VmController.prototype, "deleteVmTag", null);
 __decorate([
     Example(vmDashboard),
+    Extension('x-mcp-exposure', 'allow'),
     Get('{id}/dashboard'),
     Middlewares(acl({ resource: 'vm', action: 'read', objectId: 'params.id' })),
     Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
@@ -965,6 +1039,7 @@ __decorate([
 ], VmController.prototype, "getVmDashboard", null);
 __decorate([
     Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
     Post('{id}/actions/migrate'),
     Middlewares(json()),
     SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),

package/dist/vms/vm.service.mjs

@@ -146,6 +146,23 @@ export class VmService {
         });
         return alarms;
     }
+    async updateVm(id, body) {
+        const { resourceSet, share, ...editProps } = body;
+        // Touch the object so 404 is raised before any side effect.
+        void this.#restApi.getObject(id, 'VM');
+        const xoApp = this.#restApi.xoApp;
+        if (resourceSet !== undefined) {
+            await xoApp.setVmResourceSet(id, resourceSet, true);
+        }
+        else if (share) {
+            // `share: false` is a no-op.
+            await xoApp.shareVmResourceSet(id);
+        }
+        if (Object.keys(editProps).length === 0) {
+            return;
+        }
+        await xoApp.getXapi(id).editVm(id, editProps);
+    }
     #getDashboardQuickInfo(id) {
         const { power_state, uuid, name_description, CPUs, mainIpAddress, os_version, memory, creation, $pool, virtualizationMode, tags, $container, startTime, pvDriversDetected, pvDriversVersion, pvDriversUpToDate, } = this.#restApi.getObject(id, 'VM');
         return {

package/dist/xoa/xoa.controller.mjs

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Controller, Example, Get, Query, Request, Response, Route, Security, Tags } from 'tsoa';
+import { Controller, Example, Extension, Get, Query, Request, Response, Route, Security, Tags } from 'tsoa';
 import { inject } from 'inversify';
 import { PassThrough } from 'node:stream';
 import { provide } from 'inversify-binding-decorators';
@@ -58,6 +58,7 @@ let XoaController = class XoaController extends Controller {
 };
 __decorate([
     Example(xoaDashboard),
+    Extension('x-mcp-exposure', 'allow'),
     Get('dashboard'),
     Response(badRequestResp.status, badRequestResp.description),
     Response(unauthorizedResp.status, unauthorizedResp.description),
@@ -67,11 +68,13 @@ __decorate([
 __decorate([
     Security('none'),
     Example(pingResponse),
+    Extension('x-mcp-exposure', 'allow'),
     Get('ping')
 ], XoaController.prototype, "ping", null);
 __decorate([
     Security('none'),
     Example(guiRoutes),
+    Extension('x-mcp-exposure', 'allow'),
     Get('gui-routes')
 ], XoaController.prototype, "getGuiRoutes", null);
 XoaController = __decorate([

package/eslint-rules/index.cjs

@@ -0,0 +1,7 @@
+'use strict'
+
+module.exports = {
+  rules: {
+    'require-mcp-expose': require('./require-mcp-expose.cjs'),
+  },
+}

package/eslint-rules/require-mcp-expose.cjs

@@ -0,0 +1,129 @@
+'use strict'
+
+/**
+ * Require `@Extension('x-mcp-exposure', 'allow' | 'confirm' | 'deny')` next to
+ * every `@Get/@Post/@Put/@Patch/@Delete` method. tsoa detects extension
+ * decorators by AST identifier name, so the `Extension` literal must appear in
+ * source — a `@McpExpose` wrapper would not be picked up.
+ *
+ * Scope: this is a SURFACE-CONTROL policy, not a security control. The value
+ * only decides which endpoints the official `@xen-orchestra/mcp` server turns
+ * into LLM tools; the REST API itself never reads `x-mcp-exposure`. Every
+ * endpoint stays gated by its own RBAC/ACL middleware regardless of this
+ * annotation, and any REST client with valid credentials (including a
+ * non-official MCP) can still call a `'deny'`-tagged endpoint directly. The
+ * rule only guarantees the exposure decision is made explicitly per endpoint —
+ * it does not harden the REST API.
+ */
+
+const HTTP_METHOD_DECORATORS = new Set(['Get', 'Post', 'Put', 'Patch', 'Delete'])
+const MCP_EXPOSURE_KEY = 'x-mcp-exposure'
+const VALID_EXPOSURES = new Set(['allow', 'confirm', 'deny'])
+
+function getDecoratorCalleeName(decorator) {
+  const expr = decorator.expression
+  if (!expr) return undefined
+  if (expr.type === 'CallExpression' && expr.callee && expr.callee.type === 'Identifier') {
+    return expr.callee.name
+  }
+  if (expr.type === 'Identifier') {
+    return expr.name
+  }
+  return undefined
+}
+
+function findHttpMethodDecorator(decorators) {
+  for (const decorator of decorators) {
+    const name = getDecoratorCalleeName(decorator)
+    if (name !== undefined && HTTP_METHOD_DECORATORS.has(name)) {
+      return { decorator, name }
+    }
+  }
+  return undefined
+}
+
+function getStringLiteralValue(node) {
+  if (!node) return undefined
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length === 1) {
+    return node.quasis[0].value.cooked
+  }
+  return undefined
+}
+
+function findMcpExposureExtension(decorators) {
+  for (const decorator of decorators) {
+    if (!decorator.expression || decorator.expression.type !== 'CallExpression') continue
+    const callee = decorator.expression.callee
+    if (!callee || callee.type !== 'Identifier' || callee.name !== 'Extension') continue
+
+    const [keyArg, valueArg] = decorator.expression.arguments
+    const key = getStringLiteralValue(keyArg)
+    if (key !== MCP_EXPOSURE_KEY) continue
+
+    return { decorator, valueArg }
+  }
+  return undefined
+}
+
+function getMethodName(methodNode) {
+  if (!methodNode.key) return '<anonymous>'
+  if (methodNode.key.type === 'Identifier') return methodNode.key.name
+  if (methodNode.key.type === 'Literal') return String(methodNode.key.value)
+  return '<computed>'
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Every REST endpoint must declare its MCP exposure with @Extension("x-mcp-exposure", "allow" | "confirm" | "deny").',
+    },
+    schema: [],
+    messages: {
+      missingMcpExpose:
+        'Endpoint "{{name}}" decorated with @{{httpMethod}} is missing an @Extension("x-mcp-exposure", ...) decorator. ' +
+        'Add @Extension("x-mcp-exposure", "allow"), "confirm", or "deny" to make the MCP exposure decision explicit.',
+      invalidMcpExpose:
+        'Endpoint "{{name}}" has @Extension("x-mcp-exposure", ...) with an invalid value. ' +
+        'Expected one of: "allow", "confirm", "deny". Got: {{got}}.',
+    },
+  },
+  create(context) {
+    return {
+      MethodDefinition(node) {
+        if (node.kind === 'constructor') return
+        const decorators = node.decorators
+        if (!decorators || decorators.length === 0) return
+
+        const httpMethod = findHttpMethodDecorator(decorators)
+        if (!httpMethod) return
+
+        const methodName = getMethodName(node)
+        const mcpExposure = findMcpExposureExtension(decorators)
+
+        if (!mcpExposure) {
+          context.report({
+            node,
+            messageId: 'missingMcpExpose',
+            data: { name: methodName, httpMethod: httpMethod.name },
+          })
+          return
+        }
+
+        const exposureValue = getStringLiteralValue(mcpExposure.valueArg)
+        if (exposureValue === undefined || !VALID_EXPOSURES.has(exposureValue)) {
+          context.report({
+            node: mcpExposure.valueArg ?? mcpExposure.decorator,
+            messageId: 'invalidMcpExpose',
+            data: {
+              name: methodName,
+              got: exposureValue === undefined ? '<non-literal>' : JSON.stringify(exposureValue),
+            },
+          })
+        }
+      },
+    }
+  },
+}