fix: normalize packages (#9917)

* fix: normalize packages

no changelog since it does not need any release

* put back lost chanegs

@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([
+const [httpAddr, httpsAddr] = await Promise.all([server.listen({ port: 80 }), server.listen({ port: 443, cert, key })])
-  server.listen({ port: 80 }),
-  server.listen({ port: 443, cert, key }),
-])
 console.log('listening on', httpAddr, httpsAddr)
 ```
 

@xen-orchestra/qa-test/.npmignore

@@ -0,0 +1 @@
+../../scripts/npmignore

@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/<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: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`.

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
 

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).           |

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)

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).