diff --git a/@vates/http-server-plus/README.md b/@vates/http-server-plus/README.md index e66cee3d54..e6fbb9eba9 100644 --- a/@vates/http-server-plus/README.md +++ b/@vates/http-server-plus/README.md @@ -2,8 +2,18 @@ # @vates/http-server-plus +[![Package Version](https://badgen.net/npm/v/@vates/http-server-plus)](https://npmjs.org/package/@vates/http-server-plus) ![License](https://badgen.net/npm/license/@vates/http-server-plus) [![PackagePhobia](https://badgen.net/bundlephobia/minzip/@vates/http-server-plus)](https://bundlephobia.com/result?p=@vates/http-server-plus) [![Node compatibility](https://badgen.net/npm/node/@vates/http-server-plus)](https://npmjs.org/package/@vates/http-server-plus) + > Augmented `http.Server`, HTTP/HTTPS/HTTP2 and multiple ports on the same instance +## Install + +Installation of the [npm package](https://npmjs.org/package/@vates/http-server-plus): + +```sh +npm install --save @vates/http-server-plus +``` + ## Usage ### `create([opts], [requestListener])` @@ -48,10 +58,7 @@ await server.listen({ systemdSocket: 0 }) Multiple endpoints can be started on the same instance: ```js -const [httpAddr, httpsAddr] = await Promise.all([ - server.listen({ port: 80 }), - server.listen({ port: 443, cert, key }), -]) +const [httpAddr, httpsAddr] = await Promise.all([server.listen({ port: 80 }), server.listen({ port: 443, cert, key })]) console.log('listening on', httpAddr, httpsAddr) ``` diff --git a/@xen-orchestra/qa-test/.npmignore b/@xen-orchestra/qa-test/.npmignore new file mode 120000 index 0000000000..008d1b9b98 --- /dev/null +++ b/@xen-orchestra/qa-test/.npmignore @@ -0,0 +1 @@ +../../scripts/npmignore \ No newline at end of file diff --git a/@xen-orchestra/rest-api/.USAGE.md b/@xen-orchestra/rest-api/.USAGE.md index 846b925763..8ea0950c09 100644 --- a/@xen-orchestra/rest-api/.USAGE.md +++ b/@xen-orchestra/rest-api/.USAGE.md @@ -42,4 +42,104 @@ 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/.example.mts` +In order not to pollute important decorators, all example structures should be in a separate file. `src/open-api/oa-examples/.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:nameLabel', 'update:nameDescription'])` checks if `nameLabel` is present in the request body, and then applies the ACL check. The same applies to `nameDescription`. + +`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 + +```ts +/** + * Create a new VDI + * + * Required privilege: + * - resource: vdi, action: create + */ + @Post('/') + @Middlewares(acl({resource: 'vdi', action: 'create', object: ({req}) => req.body })) + @Response(403) + createVdi(@Body() body: VdiConfig) { + const {srId, ...rest} + const bodyParam = {$SR: srId, ...rest} + await VDI_create(bodyParam) + // ... + } +``` + +##### Example: Resource update + +```ts +/** + * Update a VM + * + * Required privileges: + * - resource: vm, action: update (grants all fields) + * - resource: vm, action: update:nameLabel (if nameLabel is passed) + * - resource: vm, action: update:nameDescription (if nameDescription is passed) + */ + @Patch('{id}') + @Middlewares(acl({resource: 'vm', actions: actionsFromBody(['update:nameLabel', 'update:nameDescription']), 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`. diff --git a/packages/xo-server-audit/README.md b/packages/xo-server-audit/README.md index 52676a4267..8190989101 100644 --- a/packages/xo-server-audit/README.md +++ b/packages/xo-server-audit/README.md @@ -7,7 +7,7 @@ ## Usage Like all other xo-server plugins, it can be configured directly via -the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). +the web interface, see [the plugin documentation](https://docs.xen-orchestra.com/architecture#plugins). ## Contributions diff --git a/packages/xo-server-sdn-controller/.USAGE.md b/packages/xo-server-sdn-controller/.USAGE.md index ce9fa1e0e2..0cb0678726 100644 --- a/packages/xo-server-sdn-controller/.USAGE.md +++ b/packages/xo-server-sdn-controller/.USAGE.md @@ -14,3 +14,57 @@ Please see the plugin's [official documentation](https://docs.xen-orchestra.com/ - `openflow-channel.js`: manages OpenFlow rules - `ovsdb-client.js`: manages private networks - `utils/tls-helper.js`: small class to create connections using TLS + +## Rest Routes + +Some rest api routes are undocumented in the swagger, here is how to use them : + +Creates a new rule +POST /vifs/{id}/actions/add_traffic_rule : + +### Fields + +| Field | Type | Required | Description | +| ----------- | --------------------- | -------- | -------------------------------------------------------------------------------------------- | +| `allow` | string (boolean-like) | Yes | Indicates whether the rule allows or denies traffic. Expected values: `"true"` or `"false"`. | +| `direction` | string | Yes | Traffic direction the rule applies to. Values: `"from"`, `"to"`, `"both"`. | +| `ipRange` | string | Yes | IP address or range. Example: `"111.168.1.2"` or `"111.168.1.0/24"`. | +| `port` | string | No | Port or port range. Empty string means all ports. Example: `"80"` or `"1000-2000"`. | +| `protocol` | string | Yes | Network protocol. Common values: `"TCP"`, `"UDP"`, `"IP"` (any protocol). | + +Deletes a new rule +POST /vifs/{id}/actions/delete_traffic_rule : + +### Fields + +| Field | Type | Required | Description | +| ----------- | ------ | -------- | ----------------------------------------------------------------------------------- | +| `direction` | string | Yes | Traffic direction the rule applies to. Values: `"from"`, `"to"`, `"both"`. | +| `ipRange` | string | Yes | IP address or range. Example: `"111.168.1.2"` or `"111.168.1.0/24"`. | +| `port` | string | No | Port or port range. Empty string means all ports. Example: `"80"` or `"1000-2000"`. | +| `protocol` | string | Yes | Network protocol. Common values: `"TCP"`, `"UDP"`, `"IP"` (any protocol). | + +Creates a new rule at network level +POST /networks/{id}/actions/add_traffic_rule : + +### Fields + +| Field | Type | Required | Description | +| ----------- | --------------------- | -------- | -------------------------------------------------------------------------------------------- | +| `allow` | string (boolean-like) | Yes | Indicates whether the rule allows or denies traffic. Expected values: `"true"` or `"false"`. | +| `direction` | string | Yes | Traffic direction the rule applies to. Values: `"from"`, `"to"`, `"both"`. | +| `ipRange` | string | Yes | IP address or range. Example: `"111.168.1.2"` or `"111.168.1.0/24"`. | +| `port` | string | No | Port or port range. Empty string means all ports. Example: `"80"` or `"1000-2000"`. | +| `protocol` | string | Yes | Network protocol. Common values: `"TCP"`, `"UDP"`, `"IP"` (any protocol). | + +Deletes a new rule at network level +POST /networks/{id}/actions/delete_traffic_rule : + +### Fields + +| Field | Type | Required | Description | +| ----------- | ------ | -------- | ----------------------------------------------------------------------------------- | +| `direction` | string | Yes | Traffic direction the rule applies to. Values: `"from"`, `"to"`, `"both"`. | +| `ipRange` | string | Yes | IP address or range. Example: `"111.168.1.2"` or `"111.168.1.0/24"`. | +| `port` | string | No | Port or port range. Empty string means all ports. Example: `"80"` or `"1000-2000"`. | +| `protocol` | string | Yes | Network protocol. Common values: `"TCP"`, `"UDP"`, `"IP"` (any protocol). | diff --git a/packages/xo-server-sdn-controller/README.md b/packages/xo-server-sdn-controller/README.md index fadbc5703e..11aa2a7fbd 100644 --- a/packages/xo-server-sdn-controller/README.md +++ b/packages/xo-server-sdn-controller/README.md @@ -23,21 +23,6 @@ Please see the plugin's [official documentation](https://docs.xen-orchestra.com/ - `ovsdb-client.js`: manages private networks - `utils/tls-helper.js`: small class to create connections using TLS -## Contributions - -Contributions are _very_ welcomed, either on the documentation or on -the code. - -You may: - -- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) - you've encountered; -- fork and create a pull request. - -## License - -[AGPL-3.0-or-later](https://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) - ## Rest Routes Some rest api routes are undocumented in the swagger, here is how to use them : @@ -91,3 +76,18 @@ POST /networks/{id}/actions/delete_traffic_rule : | `ipRange` | string | Yes | IP address or range. Example: `"111.168.1.2"` or `"111.168.1.0/24"`. | | `port` | string | No | Port or port range. Empty string means all ports. Example: `"80"` or `"1000-2000"`. | | `protocol` | string | Yes | Network protocol. Common values: `"TCP"`, `"UDP"`, `"IP"` (any protocol). | + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](https://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-transport-xmpp/.USAGE.md b/packages/xo-server-transport-xmpp/.USAGE.md index 7076801ca0..0ef2547346 100644 --- a/packages/xo-server-transport-xmpp/.USAGE.md +++ b/packages/xo-server-transport-xmpp/.USAGE.md @@ -1,2 +1,2 @@ Like all other xo-server plugins, it can be configured directly via -the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). +the web interface, see [the plugin documentation](https://docs.xen-orchestra.com/architecture#plugins).