@xen-orchestra/rest-api 0.29.0 → 0.30.0

package/README.md

@@ -60,7 +60,114 @@ class Foo extends Controller {
 
 ### Examples
 
-In order not to pollute important decorators, all example structures should be in a separate file. `src/open-api/examples/<resource>.example.mts`
+In order not to pollute important decorators, all example structures should be in a separate file. `src/open-api/oa-examples/<resource>.oa-example.mts`
+
+### ACLs
+
+To define an ACL for an endpoint, simply add the `acl` middleware and pass the required ACL(s).
+
+If an endpoint does not have a middleware ACL, it will be accessible **ONLY** to administrators.
+
+It is sometimes necessary to check ACLs based on the body of the request sent by the user (for example, for a PATCH endpoint). For this, you can use `actions` (which allows you to pass multiple actions) and `actionsFromBody` (a function exported from `acl.middleware.mts`).
+
+`actionsFromBody(['update:name_label', 'update:name_description'])` checks if `name_label` is present in the request body, and then applies the ACL check. The same applies to `name_description`.
+
+`actionIfNotSelfUser('read')` returns the given action only if the current user is **not** the target user. If the current user is the target (self), no action is returned and the ACL check is skipped entirely.
+
+#### Guidelines
+
+- **JSDoc Documentation**: Always document the required privileges in the JSDoc annotation so users know which permissions are needed. Use the format: `Required privilege: - ...`
+- **Error Handling**: If you define an ACL for an endpoint, you **must** add a `@Response(403)` decorator.
+- **Non XAPI objects**: When dealing with non XAPI XO Record, you must define the `getObject` function.
+
+##### Example: ACL on an existing resource
+
+```ts
+ /**
+  * Start a VM
+  *
+  * Required privilege:
+  * - resource: vm, action: start
+  */
+ @Post('{id}/actions/start')
+ @Middlewares(acl({resource: 'vm', action: 'start', objectId: 'params.id'}))
+ @Response(403)
+ getVm(@Path() id: string) {
+    const action = async () => {
+      const vm = await this.getObject(id)
+      // ...
+    }
+ }
+```
+
+##### Example: Resource creation
+
+When creating a resource (which doesn't exist yet), pass the object being created as the target:
+
+```ts
+/**
+  * Create a new VDI
+  *
+  * Required privilege:
+  * - resource: vdi, action: create
+  */
+ @Post('/')
+ @Middlewares(acl({resource: 'vdi', action: 'create', object: ({req}) => {
+  const {srId,...rest} = req.body
+  return {$SR: srId, ...rest}
+ }}))
+ @Response(403)
+ createVdi(@Body() body: VdiConfig) {
+   const {srId, ...rest}
+   const bodyParam = {$SR: srId, ...rest}
+   await VDI_create(bodyParam)
+   // ...
+ }
+```
+
+##### Example: Resource update
+
+When creating a resource (which doesn't exist yet), pass the object being created as the target:
+
+```ts
+/**
+ * Update a VM
+ *
+   * Required privileges:
+   * - resource: vm, action: update (grants all fields)
+   * - resource: vm, action: update:name_label (if name_label is passed)
+   * - resource: vm, action: update:name_description (if name_description is passed)
+  */
+ @Patch('{id}')
+ @Middlewares(acl({resource: 'vm', actions: actionsFromBody(['update:name_label', 'update:name_description']), objectId: 'params.id'}))
+ @Response(403)
+ createVdi(@Path() id: string, @Body() body: patchBody) {
+  updateVm(id, body)
+// ...
+ }
+```
+
+##### Example: Self-bypass ACL
+
+```ts
+/**
+ * Get a user
+ *
+ * Required privilege:
+ * - resource: user, action: read (if not self)
+ */
+@Get('{id}')
+@Middlewares(acl({
+  resource: 'user',
+  actions: actionsIfNotSelfUser(['read']),
+  objectId: 'params.id',
+  getObject: ({ restApi }) => restApi.xoApp.getUser,
+}))
+@Response(403)
+getUser(@Path() id: string) { ... }
+```
+
+If you need to use a privilege that doesn't exist yet (e.g., `resource: 'vm', action: 'foo'`), you must register it in ACL Definition: here `@xen-orchestra/acl/src/actions/vm.mts`, add: `foo: true`.
 
 ## Contributions
 

package/dist/abstract-classes/base-controller.mjs

@@ -2,6 +2,7 @@ import { Controller } from 'tsoa';
 import { createGzip } from 'node:zlib';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
+import { hasPrivilegeOn, } from '@xen-orchestra/acl';
 import { BASE_URL } from '../index.mjs';
 import { makeMarkdownTable } from '../helpers/markdown.helper.mjs';
 import { makeNdJsonStream } from '../helpers/stream.helper.mjs';
@@ -17,9 +18,23 @@ export class BaseController extends Controller {
         this.type = type;
         this.restApi = restApi;
     }
-    sendObjects(objects, req, path) {
-        const mapper = makeObjectMapper(req, path);
-        const mappedObjects = objects.map(mapper);
+    async sendObjects(objects, req, opts) {
+        const mapper = makeObjectMapper(req, opts?.path);
+        const mappedObjects = [];
+        const user = this.restApi.getCurrentUser();
+        const userPrivileges = (opts?.privilege !== undefined ? await this.restApi.xoApp.getAclV2UserPrivileges(user.id) : []);
+        let limit = opts?.limit ?? Infinity;
+        for (const object of objects) {
+            if (limit === 0) {
+                break;
+            }
+            if (opts?.privilege !== undefined &&
+                !hasPrivilegeOn({ user, userPrivileges, objects: object, ...opts.privilege })) {
+                continue;
+            }
+            mappedObjects.push(mapper(object));
+            limit--;
+        }
         if (req.query.ndjson === 'true' && req.query.markdown === 'true') {
             throw invalidParameters('Cannot use both ndjson and markdown output formats simultaneously');
         }

package/dist/abstract-classes/listener.mjs

@@ -1,11 +1,20 @@
+import { createLogger } from '@xen-orchestra/log';
+import { hasPrivilegeOn } from '@xen-orchestra/acl';
+import { iocContainer } from '../ioc/ioc.mjs';
+import { RestApi } from '../rest-api/rest-api.mjs';
+import { XAPI_TYPE_BY_ACL_RESOURCE } from '../middlewares/acl.middleware.mjs';
+const log = createLogger('xo:rest-api:listener');
 export class Listener {
     #subscribers = new Map();
     #eventEmitter;
     #eventCallbacks = new Map();
     #watchedEvent;
-    constructor(eventEmitter, watchedEvent) {
+    #type;
+    constructor(eventEmitter, watchedEvent, type) {
         this.#eventEmitter = eventEmitter;
         this.#watchedEvent = watchedEvent;
+        // cast needed because Type !== Type | undefined (even if Type extends undefined...)
+        this.#type = type;
     }
     get subscribers() {
         return this.#subscribers;
@@ -13,6 +22,9 @@ export class Listener {
     get eventEmitter() {
         return this.#eventEmitter;
     }
+    get type() {
+        return this.#type;
+    }
     addSubscriber(subscriber, fields = '*') {
         const unregisterOnClear = subscriber.onClear(() => this.removeSubscriber(subscriber.id));
         this.#subscribers.set(subscriber.id, { fields, subscriber, unregisterOnClear });
@@ -45,20 +57,112 @@ export class Listener {
         if (this.#eventCallbacks.has(event)) {
             return;
         }
-        const broadcastAllSubscriber = (...args) => {
-            this.#subscribers.forEach(conf => {
-                if (!conf.subscriber.isAlive) {
-                    this.removeSubscriber(conf.subscriber.id);
+        const broadcastAllSubscriber = async (...args) => {
+            try {
+                await Promise.all([...this.#subscribers.values()].map(async (conf) => {
+                    if (!conf.subscriber.isAlive) {
+                        this.removeSubscriber(conf.subscriber.id);
+                        return;
+                    }
+                    let data;
+                    try {
+                        data = await this.handleData({ ...conf, event }, ...args);
+                    }
+                    catch (error) {
+                        log.error(`cannot handle data for ${this.type} listener on subscriber: ${conf.subscriber.id} (user: ${conf.subscriber.userId}). Removing it from the subscriber list.`, { error });
+                        this.removeSubscriber(conf.subscriber.id);
+                        conf.subscriber.clear();
+                        return;
+                    }
+                    if (data === undefined) {
+                        return;
+                    }
+                    const { event: overridenEvent, ...dataToBroadcast } = data;
+                    conf.subscriber.broadcast(overridenEvent ?? event, dataToBroadcast);
+                }));
+            }
+            catch (error) {
+                log.warn('unexpected error broadcasting to subscribers', { error });
+            }
+        };
+        this.#eventCallbacks.set(event, broadcastAllSubscriber);
+        this.#eventEmitter.on(event, broadcastAllSubscriber);
+    }
+    async getAclEvent({ event, object, previousObject, userId, }) {
+        if (this.type === undefined || (object === undefined && previousObject === undefined)) {
+            return;
+        }
+        const restApi = iocContainer.get(RestApi);
+        const user = await restApi.xoApp.getUser(userId);
+        if (user.permission === 'admin') {
+            return event;
+        }
+        const userPrivileges = (await restApi.xoApp.getAclV2UserPrivileges(user.id));
+        let resource;
+        // alarm and task are not real `XAPI` type
+        if (this.type === 'alarm' || this.type === 'task') {
+            resource = this.type;
+        }
+        else {
+            const resourceXapiType = Object.entries(XAPI_TYPE_BY_ACL_RESOURCE).find(([, xapiType]) => xapiType === this.type);
+            if (resourceXapiType === undefined) {
+                throw new Error(`No resource found for ${this.type} listener type`);
+            }
+            // cast is necessary because `Object.entries` loses inference on the key (it transforms it into a simple string).
+            ;
+            [resource] = resourceXapiType;
+        }
+        switch (event) {
+            case 'add':
+                if (object === undefined) {
                     return;
                 }
-                const data = this.handleData({ ...conf, event }, ...args);
-                if (data === undefined) {
+                if (!hasPrivilegeOn({ user, userPrivileges, action: 'read', objects: object, resource })) {
                     return;
                 }
-                conf.subscriber.broadcast(event, data);
-            });
-        };
-        this.#eventCallbacks.set(event, broadcastAllSubscriber);
-        this.#eventEmitter.on(event, broadcastAllSubscriber);
+                return 'add';
+            case 'update': {
+                const canSeeObject = object !== undefined &&
+                    hasPrivilegeOn({
+                        user,
+                        userPrivileges,
+                        action: 'read',
+                        objects: object,
+                        resource,
+                    });
+                const canSeePreviousObject = previousObject !== undefined &&
+                    hasPrivilegeOn({
+                        user,
+                        userPrivileges,
+                        action: 'read',
+                        objects: previousObject,
+                        resource,
+                    });
+                if (canSeeObject && canSeePreviousObject) {
+                    return 'update';
+                }
+                if (canSeeObject) {
+                    return 'add';
+                }
+                if (canSeePreviousObject) {
+                    return 'remove';
+                }
+                return;
+            }
+            case 'remove':
+                if (!hasPrivilegeOn({
+                    user,
+                    userPrivileges,
+                    action: 'read',
+                    objects: object ?? previousObject,
+                    resource,
+                })) {
+                    return;
+                }
+                return 'remove';
+            default:
+                // Not supposed to be here
+                throw new Error(`${event} event unhandled on ${this.type} listener`);
+        }
     }
 }

package/dist/acl-privileges/acl-privilege.controller.mjs

@@ -0,0 +1,172 @@
+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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Delete, Example, Get, Middlewares, Patch, Path, Post, Query, Request, Response, Route, Security, SuccessResponse, Tags, } from 'tsoa';
+import { provide } from 'inversify-binding-decorators';
+import { json } from 'express';
+import { acl, actionsFromBody } from '../middlewares/acl.middleware.mjs';
+import { aclPrivilege, aclPrivilegeIds, partialAclPrivileges, } from '../open-api/oa-examples/acl-privilege.oa-example.mjs';
+import { badRequestResp, createdResp, forbiddenOperationResp, invalidParameters, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
+import { XoController } from '../abstract-classes/xo-controller.mjs';
+import { entityId } from '../open-api/oa-examples/common.oa-example.mjs';
+import { inject } from 'inversify';
+import { RestApi } from '../rest-api/rest-api.mjs';
+let AclPrivilegeController = class AclPrivilegeController extends XoController {
+    constructor(restApi) {
+        super('acl-privilege', restApi);
+    }
+    getAllCollectionObjects() {
+        return this.restApi.xoApp.getAclV2Privileges();
+    }
+    getCollectionObject(id) {
+        return this.restApi.xoApp.getAclV2Privilege(id);
+    }
+    /**
+     * Returns all ACL privileges that match the following privilege:
+     * - resource: acl-privilege, action: read
+     *
+     * @example fields "id,action,resource"
+     * @example filter "action:create"
+     * @example limit 42
+     */
+    async getAclV2Privileges(req, fields, ndjson, filter, limit) {
+        return this.sendObjects(Object.values(await this.getObjects({ filter })), req, {
+            limit,
+            privilege: { action: 'read', resource: 'acl-privilege' },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: acl-privilege, action: create
+     *
+     * @example privilege {
+     *  "action": "read",
+     *  "resource": "alarm",
+     *  "roleId": "784bd959-08de-4b26-b575-92ded5aef872",
+     *  "effect": "allow",
+     *  "selector": "id:784bd959-08de-4b26-b575-92ded5aef872"
+     * }
+     */
+    async createAclV2Privilege(privilege) {
+        const newPrivilege = await this.restApi.xoApp.createAclV2Privilege(privilege);
+        return { id: newPrivilege.id };
+    }
+    /**
+     * Required privilege:
+     * - resource: acl-privilege, action: read
+     *
+     * @example id "c5d89d1a-df1e-4b72-98a0-c40adfdf49c1"
+     */
+    getAclV2Privilege(id) {
+        return this.getObject(id);
+    }
+    /**
+     * Required privilege:
+     * - resource: acl-privilege, action: delete
+     *
+     * @example id "784bd959-08de-4b26-b575-92ded5aef872"
+     */
+    async deleteAclV2Privilege(id) {
+        await this.restApi.xoApp.deleteAclV2Privilege(id);
+    }
+    /**
+     * Required privileges:
+     * - resource: acl-privilege, action: update (grants all fields)
+     * - resource: acl-privilege, action: update:action (if action is passed)
+     * - resource: acl-privilege, action: update:resource (if resource is passed)
+     * - resource: acl-privilege, action: update:effect (if effect is passed)
+     * - resource: acl-privilege, action: update:selector (if selector is passed)
+     *
+     * @example id "784bd959-08de-4b26-b575-92ded5aef872"
+     * @example privilege {
+     *  "action": "read",
+     *  "resource": "alarm",
+     *  "effect": "allow",
+     *  "selector": "id:784bd959-08de-4b26-b575-92ded5aef872"
+     * }
+     */
+    async updateAclV2Privilege(id, privilege) {
+        await this.restApi.xoApp.updateAclV2Privilege(id, privilege);
+    }
+};
+__decorate([
+    Example(aclPrivilegeIds),
+    Example(partialAclPrivileges),
+    Get(''),
+    Security('*', ['acl']),
+    __param(0, Request()),
+    __param(1, Query()),
+    __param(2, Query()),
+    __param(3, Query()),
+    __param(4, Query())
+], AclPrivilegeController.prototype, "getAclV2Privileges", null);
+__decorate([
+    Example(entityId),
+    Post(''),
+    Middlewares([json(), acl({ resource: 'acl-privilege', action: 'create', object: ({ req }) => req.body })]),
+    SuccessResponse(createdResp.status, createdResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(invalidParameters.status, invalidParameters.description),
+    __param(0, Body())
+], AclPrivilegeController.prototype, "createAclV2Privilege", null);
+__decorate([
+    Example(aclPrivilege),
+    Get('{id}'),
+    Middlewares(acl({
+        resource: 'acl-privilege',
+        action: 'read',
+        objectId: 'params.id',
+        getObject: ({ restApi }) => restApi.xoApp.getAclV2Privilege,
+    })),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path())
+], AclPrivilegeController.prototype, "getAclV2Privilege", null);
+__decorate([
+    Delete('{id}'),
+    Middlewares(acl({
+        resource: 'acl-privilege',
+        action: 'delete',
+        objectId: 'params.id',
+        getObject: ({ restApi }) => restApi.xoApp.getAclV2Privilege,
+    })),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path())
+], AclPrivilegeController.prototype, "deleteAclV2Privilege", null);
+__decorate([
+    Patch('{id}'),
+    Middlewares([
+        json(),
+        acl({
+            resource: 'acl-privilege',
+            actions: actionsFromBody(['update:action', 'update:resource', 'update:effect', 'update:selector']),
+            objectId: 'params.id',
+            getObject: ({ restApi }) => restApi.xoApp.getAclV2Privilege,
+        }),
+    ]),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(invalidParameters.status, invalidParameters.description),
+    __param(0, Path()),
+    __param(1, Body())
+], AclPrivilegeController.prototype, "updateAclV2Privilege", null);
+AclPrivilegeController = __decorate([
+    Route('acl-privileges'),
+    Security('*'),
+    Response(badRequestResp.status, badRequestResp.description),
+    Response(unauthorizedResp.status, unauthorizedResp.description),
+    Tags('acls'),
+    provide(AclPrivilegeController),
+    __param(0, inject(RestApi))
+], AclPrivilegeController);
+export { AclPrivilegeController };