ldap-rest 1.2.0 → 1.3.0

package/docs/plugin-development/openapi.md

@@ -3,7 +3,15 @@
 The published API reference at <https://linagora.github.io/ldap-rest/api/> is
 generated from `openapi.json`, which itself is built statically by
 [`scripts/generate-openapi.ts`](../../scripts/generate-openapi.ts) — it walks
-every plugin's `api()` method and reads the JSDoc comments above each route.
+every plugin's `api()` method and reads the JSDoc comments above each route,
+and reads the declaration of every [`defineRoute`](routes.md) call.
+
+With `defineRoute` the declaration is the document: the generator takes its
+`summary`, `description`, `tags`, `params`, `query`, `body` and `responses`,
+and imports the exported schema constants it names. An `@openapi` block above
+the call still wins over what the declaration says — a `requestBody` it
+describes replaces the declared `body` schema whole, rather than merging into
+it — and a route registered with `app.<verb>(` still needs one.
 
 You don't need to touch the generator to enrich your plugin's documentation.
 Two JSDoc directives drive the entire pipeline:
@@ -139,6 +147,11 @@ npm run generate:openapi   # writes openapi.json
 npm run build:pages        # rebuilds the static site under _site/
 ```
 
+`openapi.json` is committed: it is what the site publishes, so a change to a
+route or to a schema it declares must come with a regenerated document. CI
+runs `npm run check:openapi`, which builds the spec and fails when the file
+differs, naming the first line at fault.
+
 Open `_site/api/index.html` to preview the Redoc rendering. The published
 site at <https://linagora.github.io/ldap-rest/api/> is rebuilt automatically
 on every `v*` tag push.

package/docs/plugin-development/options.md

@@ -0,0 +1,109 @@
+# Plugin options
+
+A core plugin declares its configuration options next to its code, in a
+`<plugin>.options.ts` file. A family that shares imports and lifecycle keeps
+one set per plugin in a single `<family>.options.ts` file, named after the
+family. `src/config/args.ts` concatenates those declarations,
+so the parser, the command line and the environment variables see the same
+entries as before. The plugin then reads typed values instead of casting
+`this.config`.
+
+## Declaring options
+
+```typescript
+// src/plugins/example/example.options.ts
+import { defineOptions, opt, type OptionsOf } from '../../config/options';
+
+export const exampleOptions = defineOptions({
+  example_url: opt.string({
+    env: 'DM_EXAMPLE_URL',
+    required: true,
+  }),
+  example_timeout: opt.number({
+    env: 'DM_EXAMPLE_TIMEOUT',
+    default: 5000,
+    min: 1,
+  }),
+  example_retry: opt.boolean({
+    env: 'DM_EXAMPLE_RETRY',
+    default: false,
+  }),
+  example_domains: opt.array({
+    env: 'DM_EXAMPLE_DOMAINS',
+    default: [],
+    plural: 'example-domains',
+    kind: 'identifiers',
+  }),
+});
+
+export type ExampleOptions = OptionsOf<typeof exampleOptions>;
+```
+
+The key is the `Config` name: `example_timeout` is `--example-timeout`,
+`DM_EXAMPLE_TIMEOUT` when the descriptor names that variable.
+
+Each declaration takes:
+
+| Field      | Meaning                                                             |
+| ---------- | ------------------------------------------------------------------- |
+| `env`      | Environment variable read when the CLI does not set the option      |
+| `default`  | Value kept when neither the CLI nor the environment sets the option |
+| `required` | Refuse an empty value instead of reading it as unset                |
+| `plural`   | Array only: CLI name of the plural form, without the leading `--`   |
+| `kind`     | Array only: how a value splits, see `ArrayKind` in `parseConfig.ts` |
+| `min/max`  | Number only: bounds checked when the option is read                 |
+| `choices`  | String only: the values the option accepts                          |
+
+## Reading options
+
+The plugin names the declaration as a static field, and asks for the values in
+its constructor:
+
+```typescript
+export default class Example extends DmPlugin {
+  static optionDefinitions = exampleOptions;
+  name = 'example';
+
+  private readonly settings: ExampleOptions;
+
+  constructor(server: DM) {
+    super(server);
+    this.settings = this.options(exampleOptions);
+  }
+}
+```
+
+`options(exampleOptions)` applies the defaults, copies array defaults and
+checks `required`, `min`, `max` and `choices`. The base constructor asks once,
+so a bad value stops the plugin from loading rather than failing at the first
+request. Each later call reads the configuration again rather than keeping
+the first values. `--plugin example:name:{...}` overrides still work: the view the
+plugin receives carries the merged configuration, and `options()` reads that
+view. Give it the same declaration object the class names in
+`optionDefinitions`: any other one is refused, so the generic type parameter
+cannot describe the wrong view.
+
+## Wiring it in
+
+Import the declaration in `src/config/args.ts` and spread it where the plugin's
+options used to be:
+
+```typescript
+import { exampleOptions } from '../plugins/example/example.options';
+import { toConfigEntries } from './options';
+
+const configArgs: ConfigTemplate = [
+  // ...
+  ...toConfigEntries(exampleOptions),
+];
+```
+
+The `Config` interface keeps the hand-written fields until every plugin has
+moved. A migrated plugin no longer reads them: it uses `options()`.
+
+Plugins outside the repository cannot add to `args.ts` yet, but they can
+declare options the same way and name them in `optionDefinitions`: the startup
+report subtracts those keys, and `options()` reads a declared `env` variable
+when the parser did not carry the key. An option without a declaration still
+reaches `this.config` from an unknown `--key value` pair, and the startup
+report names it.

package/docs/plugin-development/routes.md

@@ -0,0 +1,152 @@
+# Declaring routes
+
+`defineRoute` declares an HTTP route once: its inputs, their schemas, what
+the OpenAPI document says of it, and the handler. The schemas are checked
+before the handler runs, the openapi generator describes the route from the
+declaration, and the route probe finds it in the registry.
+
+```typescript
+import { Type } from '@sinclair/typebox';
+import type { Express } from 'express';
+
+import DmPlugin, { defineRoute, type Role } from '../../abstract/plugin';
+
+/** Exported: the OpenAPI generator reads it without running the plugin. */
+export const GroupParams = Type.Object({
+  cn: Type.String({ minLength: 1 }),
+});
+
+export const GroupQuery = Type.Object({
+  dryRun: Type.Optional(Type.Boolean()),
+});
+
+export const GroupMembers = Type.Object(
+  { member: Type.Union([Type.String(), Type.Array(Type.String())]) },
+  { additionalProperties: false }
+);
+
+export const MembersAdded = Type.Object({ added: Type.Number() });
+
+export default class MyPlugin extends DmPlugin {
+  name = 'myPlugin';
+  roles: Role[] = ['api'] as const;
+
+  api(app: Express): void {
+    defineRoute(app, {
+      method: 'post',
+      path: `${this.config.api_prefix}/v1/ldap/groups/:cn/members`,
+      params: GroupParams,
+      query: GroupQuery,
+      body: GroupMembers,
+      responses: {
+        200: { schema: MembersAdded, description: 'Members added' },
+      },
+      summary: 'Add members to a group',
+      tags: ['Groups'],
+      handler: async ({ params, query, body, res }) => {
+        const added = await this.addMembers(params.cn, body.member, {
+          dryRun: query.dryRun ?? false,
+        });
+        res.json({ added });
+      },
+    });
+  }
+}
+```
+
+The handler has the same duties as an `asyncHandler` callback: it answers
+through `res`, and a rejection is passed to the error middleware.
+
+## Schemas
+
+Each schema is an **exported constant**, possibly imported from another
+module. `npm run generate:openapi` does not run the plugin: it finds the
+`defineRoute` call in the source, imports the module that exports each
+schema, and reads its value — a TypeBox schema is JSON Schema already. A
+schema written inline in the declaration is checked at runtime but is not
+in the document, and the generator warns about it.
+
+Keep in mind that the schemas are part of the published API: give the
+properties a `description`, or rely on what TypeBox emits.
+
+## Inputs
+
+| Field    | Source       | Checked as |
+| -------- | ------------ | ---------- |
+| `params` | `req.params` | converted  |
+| `query`  | `req.query`  | converted  |
+| `body`   | `req.body`   | as parsed  |
+
+A route that needs a route middleware — a multipart parser, say — passes it
+as `middleware`. Express runs it before the handler, and before the `Accept`
+and schema checks: a multipart body is read before the request may be
+refused.
+
+Path and query values always arrive as strings, so they are converted before
+being checked: a `Type.Number()` query accepts `?limit=10` and hands the
+handler `10`. The body is whatever the registered parser left in `req.body`;
+a request carrying none is checked as an empty object, so an all-optional
+schema accepts it and a required field is refused by name.
+
+A part the route declares no schema for is handed to the handler unchecked,
+as before. The declaration feeds the document the same way: `params` becomes
+the path parameters, `query` the query parameters, `body` the JSON request
+body, and `responses` the answers; the standard 400/401/404/500 entries stay.
+
+An answer is a schema, or `{ schema, description }` when the document needs
+a sentence of its own:
+
+```typescript
+responses: {
+  200: { schema: MembersAdded, description: 'Members added' },
+  409: { schema: AlreadyMember, description: 'Already a member' },
+  500: ErrorSchema,
+}
+```
+
+Only the parameters the path actually carries (`:cn` → `{cn}`) become path
+parameters: a `params` key the path does not name is reported by the
+generator and left out, since OpenAPI refuses it.
+
+## Refusals
+
+A request that fails a schema is answered with `400` and a body naming every
+failing path:
+
+```json
+{
+  "error": "Invalid request: body.member: Expected string; query.limit: Expected number"
+}
+```
+
+A caller whose `Accept` excludes JSON is answered `400 Bad request` before
+the handler runs. A route serving another media type sets `json: false` and
+answers it itself; SCIM does, for `application/scim+json`. Its declared
+schemas are still checked first, and a failure there is answered in the REST
+shape (`Invalid request: …`): such a route validates the rest of its input
+itself. The handler also receives Express's `next`, for a route that falls
+through or has already answered.
+
+`Type.Object` accepts unknown keys unless the schema says
+`{ additionalProperties: false }`. A route migrated from hand-written checks
+starts without that option, so it refuses no client it accepted before;
+tighten it one route at a time.
+
+## The registry
+
+Every declaration is recorded on the app, schemas included, without its
+handler. `registeredRoutes(app)` returns them, and `unregisteredRoutes(app)`
+lists what the Express stack carries that `defineRoute` did not declare.
+
+## The migration guard
+
+`npm run lint` refuses `app.<verb>(` under `src/plugins` and `src/abstract`,
+through `eslint-rules/no-raw-route.mjs`. `eslint-rules/route-allowlist.json`
+names the files a raw route is tolerated in; it is empty, so every route in
+the tree is declared. `test/scripts/routeAllowlist.test.ts` keeps the list
+exact: a listed file must still declare a raw route, and an unlisted file
+must not.
+
+`test/security/routeValidation.test.ts` reads the registry and sends each
+declared query and body a value it must refuse, so a new declaration is
+probed without touching the test.

package/docs/plugin-development/testing.md

@@ -92,12 +92,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
 
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v7
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Install dependencies
         run: npm ci

package/docs/usage/configuration.md

@@ -149,6 +149,11 @@ of the environment variable. An empty value on the command line, such as an
 unset variable expanding to nothing, stops the server: leave the option out
 to keep the default.
 
+An option or `DM_*` variable that no declared option reads is named in a
+warning at startup. `--strict-options` refuses it instead. Kubernetes injects
+`DM_*` variables for services whose name starts with `dm`; leave the flag off
+where those names are in use.
+
 ## General Options
 
 | CLI                  | Plural           | Env                   | Default          | Description                                                                                       |
@@ -160,6 +165,7 @@ to keep the default.
 | `--logger`           |                  | `DM_LOGGER`           | `console`        | `console` or `file`, see [Logger](#logger---logger)                                               |
 | `--log-file`         |                  | `DM_LOG_FILE`         | `error.log`      | File `--logger file` writes to                                                                    |
 | `--debug`            |                  | `DM_DEBUG`            | `false`          | Name the failure in the 5xx answers of the error middleware and `serverError`; not for production |
+| `--strict-options`   |                  | `DM_STRICT_OPTIONS`   | `false`          | Refuse an option or `DM_*` variable no declared option reads                                      |
 | `--api-prefix`       |                  | `DM_API_PREFIX`       | `/api`           | API URL prefix                                                                                    |
 | `--mail-domain`      | `--mail-domains` | `DM_MAIL_DOMAIN`      | `[]`             | Mail domains                                                                                      |
 | `--schemas-path`     |                  | `DM_SCHEMAS_PATH`     | `static/schemas` | Path to JSON schemas                                                                              |
@@ -229,15 +235,15 @@ at `0` otherwise.
 
 #### `core/ldap/groups`
 
-| CLI                                | Plural            | Env                             | Default                            | Description                 |
-| ---------------------------------- | ----------------- | ------------------------------- | ---------------------------------- | --------------------------- |
-| `--ldap-group-base`                |                   | `DM_LDAP_GROUP_BASE`            |                                    | Groups base DN              |
-| `--ldap-groups-main-attribute`     |                   | `DM_LDAP_GROUPS_MAIN_ATTRIBUTE` | `cn`                               | Group identifier attribute  |
-| `--group-class`                    | `--group-classes` | `DM_GROUP_CLASSES`              | `top,groupOfNames`                 | Group objectClasses         |
-| `--group-allow-unexistent-members` |                   | `DM_ALLOW_UNEXISTENT_MEMBERS`   | `false`                            | Allow non-existent members  |
-| `--group-default-attributes`       |                   | `DM_GROUP_DEFAULT_ATTRIBUTES`   | `{}`                               | Default attributes (JSON)   |
-| `--group-dummy-user`               |                   | `DM_GROUP_DUMMY_USER`           | `cn=fakeuser`                      | Dummy user for empty groups |
-| `--group-schema`                   |                   | `DM_GROUP_SCHEMA`               | `static/schemas/twake/groups.json` | Group JSON schema path      |
+| CLI                                 | Plural            | Env                             | Default                            | Description                 |
+| ----------------------------------- | ----------------- | ------------------------------- | ---------------------------------- | --------------------------- |
+| `--ldap-group-base`                 |                   | `DM_LDAP_GROUP_BASE`            |                                    | Groups base DN              |
+| `--ldap-groups-main-attribute`      |                   | `DM_LDAP_GROUPS_MAIN_ATTRIBUTE` | `cn`                               | Group identifier attribute  |
+| `--group-class`                     | `--group-classes` | `DM_GROUP_CLASSES`              | `top,groupOfNames`                 | Group objectClasses         |
+| `--groups-allow-unexistent-members` |                   | `DM_ALLOW_UNEXISTENT_MEMBERS`   | `false`                            | Allow non-existent members  |
+| `--group-default-attributes`        |                   | `DM_GROUP_DEFAULT_ATTRIBUTES`   | `{}`                               | Default attributes (JSON)   |
+| `--group-dummy-user`                |                   | `DM_GROUP_DUMMY_USER`           | `cn=fakeuser`                      | Dummy user for empty groups |
+| `--group-schema`                    |                   | `DM_GROUP_SCHEMA`               | `static/schemas/twake/groups.json` | Group JSON schema path      |
 
 #### `core/ldap/externalUsersInGroups`
 
@@ -429,6 +435,7 @@ whichever of the two names it selects. A value other than `req.user` or
 | ---------------------------------- | ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--authz-per-branch-config`        | `DM_AUTHZ_PER_BRANCH_CONFIG`        | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                                                                                                                                                                                     |
 | `--authz-per-branch-cache-ttl`     | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`     | `60`                                             | Cache TTL (seconds)                                                                                                                                                                                                                                                                                                                             |
+| `--ldap-group-member-attribute`    | `DM_LDAP_GROUP_MEMBER_ATTRIBUTE`    | `member`                                         | Attribute a group lists its members in                                                                                                                                                                                                                                                                                                          |
 | `--authz-filter-attached-entries`  | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES`  | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch`; always on under `authzLinid1`; does nothing under `authzDynamic`.                                                                                                                                                      |
 | `--authz-transit-branch`           | `DM_AUTHZ_TRANSIT_BRANCH`           |                                                  | Organization entries are handed over through when they are judged by attachment: every administrator sees and may claim what is there, and puts an entry there with write on the organization it leaves. An entry attached to no organization is in transit too. See [authzLinid1](plugins/auth/authz-linid1.md#transit-handing-an-entry-over). |
 | `--authz-transit-origin-attribute` | `DM_AUTHZ_TRANSIT_ORIGIN_ATTRIBUTE` |                                                  | Attribute an entry put in transit keeps the organization it leaves in, removed when it is claimed. Empty records nothing; it must exist in the directory's schema. See [authzLinid1](plugins/auth/authz-linid1.md#where-an-entry-comes-from).                                                                                                   |
@@ -523,7 +530,7 @@ Formerly `core/twake/calendarResources`, still accepted as a deprecated alias.
 | `--calendar-concurrency`          | `DM_CALENDAR_CONCURRENCY`          | `10`                    | API concurrency               |
 | `--calendar-resource-base`        | `DM_CALENDAR_RESOURCE_BASE`        |                         | Resource base DN              |
 | `--calendar-resource-objectclass` | `DM_CALENDAR_RESOURCE_OBJECTCLASS` |                         | Resource objectClass          |
-| `--calendar-resource-creator`     | `DM_CALENDAR_RESOURCE_CREATOR`     |                         | Resource creator              |
+| `--calendar-resource-creator`     | `DM_CALENDAR_RESOURCE_CREATOR`     | `admin@example.com`     | Resource creator              |
 | `--calendar-resource-domain`      | `DM_CALENDAR_RESOURCE_DOMAIN`      |                         | Resource domain               |
 | `--calendar-firstname-attribute`  | `DM_CALENDAR_FIRSTNAME_ATTRIBUTE`  | `givenName`             | Registered user first name    |
 | `--calendar-lastname-attribute`   | `DM_CALENDAR_LASTNAME_ATTRIBUTE`   | `sn`                    | Registered user last name     |
@@ -643,8 +650,8 @@ Extends `core/ldap/groups`, whose options it reads too.
 
 | CLI                                           | Env                                            | Default            | Description                                           |
 | --------------------------------------------- | ---------------------------------------------- | ------------------ | ----------------------------------------------------- |
-| `--twake-group-base`                          | `DM_TWAKE_GROUP_BASE`                          |                    | Group branch of an organization, with `{org}`         |
-| `--twake-group-user-base`                     | `DM_TWAKE_GROUP_USER_BASE`                     |                    | User branch of an organization, with `{org}`          |
+| `--twake-group-base`                          | `DM_TWAKE_GROUP_BASE`                          |                    | Group branch of an organization, holding `{org}` once |
+| `--twake-group-user-base`                     | `DM_TWAKE_GROUP_USER_BASE`                     |                    | User branch of an organization, holding `{org}` once  |
 | `--twake-group-organization-dn`               | `DM_TWAKE_GROUP_ORGANIZATION_DN`               |                    | Organization entry, with `{org}` (empty: not checked) |
 | `--twake-group-organization-status-attribute` | `DM_TWAKE_GROUP_ORGANIZATION_STATUS_ATTRIBUTE` | `twakeOrgStatus`   | Organization status attribute                         |
 | `--twake-group-organization-deleted-value`    | `DM_TWAKE_GROUP_ORGANIZATION_DELETED_VALUE`    | `deleted`          | Status of a deleted organization                      |
@@ -663,17 +670,17 @@ organization entry, and `core/ldap/onChange`; with `--rabbitmq-url`, it
 requires `core/rabbitmq` and reads the organization domain from
 `--twake-instance-organization-domain-attribute`.
 
-| CLI                                    | Env                                     | Default                                | Description                                        |
-| -------------------------------------- | --------------------------------------- | -------------------------------------- | -------------------------------------------------- |
-| `--twake-space-base`                   | `DM_TWAKE_SPACE_BASE`                   |                                        | Space branch of an organization, with `{org}`      |
-| `--twake-space-class`                  | `DM_TWAKE_SPACE_CLASS`                  | `top,twakeSpace`                       | Object classes of a space                          |
-| `--twake-space-display-name-attribute` | `DM_TWAKE_SPACE_DISPLAY_NAME_ATTRIBUTE` | `twakeDisplayName`                     | Space name attribute                               |
-| `--twake-space-admin-attribute`        | `DM_TWAKE_SPACE_ADMIN_ATTRIBUTE`        | `twakeSpaceAdmin`                      | DNs holding the admin role                         |
-| `--twake-space-editor-attribute`       | `DM_TWAKE_SPACE_EDITOR_ATTRIBUTE`       | `twakeSpaceEditor`                     | DNs holding the editor role                        |
-| `--twake-space-viewer-attribute`       | `DM_TWAKE_SPACE_VIEWER_ATTRIBUTE`       | `twakeSpaceViewer`                     | DNs holding the viewer role                        |
-| `--twake-space-user-role-attribute`    | `DM_TWAKE_SPACE_USER_ROLE_ATTRIBUTE`    |                                        | User attribute holding `<space id>:<role>`, if set |
-| `--twake-space-exchange`               | `DM_TWAKE_SPACE_EXCHANGE`               | `space`                                | Topic exchange of the space events                 |
-| `--twake-space-sync-queue`             | `DM_TWAKE_SPACE_SYNC_QUEUE`             | `twake.space.sync.requested.ldap-rest` | Queue of the space sync requests                   |
+| CLI                                    | Env                                     | Default                                | Description                                           |
+| -------------------------------------- | --------------------------------------- | -------------------------------------- | ----------------------------------------------------- |
+| `--twake-space-base`                   | `DM_TWAKE_SPACE_BASE`                   |                                        | Space branch of an organization, holding `{org}` once |
+| `--twake-space-class`                  | `DM_TWAKE_SPACE_CLASS`                  | `top,twakeSpace`                       | Object classes of a space                             |
+| `--twake-space-display-name-attribute` | `DM_TWAKE_SPACE_DISPLAY_NAME_ATTRIBUTE` | `twakeDisplayName`                     | Space name attribute                                  |
+| `--twake-space-admin-attribute`        | `DM_TWAKE_SPACE_ADMIN_ATTRIBUTE`        | `twakeSpaceAdmin`                      | DNs holding the admin role                            |
+| `--twake-space-editor-attribute`       | `DM_TWAKE_SPACE_EDITOR_ATTRIBUTE`       | `twakeSpaceEditor`                     | DNs holding the editor role                           |
+| `--twake-space-viewer-attribute`       | `DM_TWAKE_SPACE_VIEWER_ATTRIBUTE`       | `twakeSpaceViewer`                     | DNs holding the viewer role                           |
+| `--twake-space-user-role-attribute`    | `DM_TWAKE_SPACE_USER_ROLE_ATTRIBUTE`    |                                        | User attribute holding `<space id>:<role>`, if set    |
+| `--twake-space-exchange`               | `DM_TWAKE_SPACE_EXCHANGE`               | `space`                                | Topic exchange of the space events                    |
+| `--twake-space-sync-queue`             | `DM_TWAKE_SPACE_SYNC_QUEUE`             | `twake.space.sync.requested.ldap-rest` | Queue of the space sync requests                      |
 
 See [spaces](plugins/integrations/spaces.md).
 
@@ -722,7 +729,7 @@ see [Storage](plugins/utilities/storage.md).
 
 #### `core/configApi`
 
-Exposes API configuration at `/api/v1/config` for client applications. Returns available features, schemas, and endpoints. No configuration options.
+Exposes API configuration at `/api/v1/config` for client applications. Returns available features, schemas, endpoints, and the server's `version` — read from the `package.json` that ships with it, so a client can tell an administrator the server is older than it supports. No configuration options.
 
 ## Configuration File
 

package/docs/usage/operations.md

@@ -41,7 +41,17 @@ and `/readyz` names the loaded plugins that report: on an ingress exposing
 the server to the internet, keep the two paths to the cluster.
 
 The Helm chart probes both routes over HTTP (`livenessProbe` and
-`readinessProbe` in `values.yaml`).
+`readinessProbe` in `values.yaml`). The published image also declares a
+`HEALTHCHECK` calling `GET /healthz` from inside the container, on `DM_PORT`:
+`docker ps` reports the container unhealthy when it stops answering, and a
+`--restart` policy restarts it as it would after a crash, while an
+orchestrator with probes of its own ignores the declaration. A port given
+any other way (`--port` in a configuration file, a plugin) leaves the check
+on 8081.
+
+The image runs as its unprivileged `node` user: with `docker run`, a
+`DM_PORT` below 1024 stops the server at startup, where the default 8081
+changes nothing.
 
 ### What the shipped plugins report
 
@@ -110,6 +120,7 @@ the rate limiting and the request id, to keep to the cluster or the host.
 | `ldap_rest_ldap_pool_wait_seconds`            | histogram |                             | Time to get a pooled connection, opening one included                                                                                                                                                                                                                                                           |
 | `ldap_rest_ldap_pool_connections`             | gauge     | `state`                     | Pooled connections, `busy` or `idle`                                                                                                                                                                                                                                                                            |
 | `ldap_rest_ldap_pool_waiting`                 | gauge     |                             | Operations waiting for a connection, the pool being full                                                                                                                                                                                                                                                        |
+| `ldap_rest_ldap_pool_opening`                 | gauge     |                             | Connections being opened, within `--ldap-pool-size`                                                                                                                                                                                                                                                             |
 | `ldap_rest_ldap_pool_max`                     | gauge     |                             | `--ldap-pool-size`                                                                                                                                                                                                                                                                                              |
 | `ldap_rest_ldap_search_cache_total`           | counter   | `result`                    | Cacheable searches, `hit` or `miss`; nothing when the cache is off                                                                                                                                                                                                                                              |
 | `ldap_rest_hook_failures_total`               | counter   | `hook`, `plugin`            | Notification hooks (`*done`, `onLdap*`) that threw, which the server logs and goes on                                                                                                                                                                                                                           |
@@ -117,6 +128,10 @@ the rate limiting and the request id, to keep to the cluster or the host.
 | `ldap_rest_unhandled_rejections_total`        | counter   |                             | Promise rejections nothing handled; counted by the binary, a host skipping `exitOnCrash()` leaves it at zero                                                                                                                                                                                                    |
 | `process_*`, `nodejs_*`                       |           |                             | The process: CPU, memory, event loop lag, handles, GC                                                                                                                                                                                                                                                           |
 
+A burst of requests that has to open connections no longer opens one per
+request: a connection being opened takes its place in the pool, and the
+requests over `--ldap-pool-size` wait for a free one.
+
 A search the caller pages is timed page by page, what the caller does
 between two pages left out; the readiness ping is not timed. The route
 label is the template a route was declared with, never the URL: a label
@@ -128,9 +143,9 @@ James's does, is a call like another. A plugin calling a service through
 `this.fetch` has its calls counted under its name; the OpenID Connect
 client's calls to its provider are made by its library, and not timed.
 
-The instruments come from `prom-client` 15, kept while the server supports
-Node 20, which its successor `@prometheus-io/client` dropped: the
-deprecation notice `npm install` prints is expected.
+The instruments come from `prom-client` 15, which `npm install` reports as
+deprecated: its successor `@prometheus-io/client` is the migration to make,
+and the notice is expected until it is done.
 
 The port listens on every interface. What to alert on: `/readyz` for a
 replica out of rotation, `result="error"` in

package/docs/usage/plugins/integrations/groups.md

@@ -137,8 +137,8 @@ for it.
   describes department groups and requires `twakeDepartmentLink`, which these
   groups do not have. Groups created through SCIM are written directly and
   are not checked against this schema.
-- `--twake-group-base`, `--twake-group-user-base`: required, each with
-  `{org}`.
+- `--twake-group-base`, `--twake-group-user-base`: required, each holding
+  `{org}` once.
 - `--twake-group-organization-dn`: the organization entry. Empty means no
   organization is checked.
 - `--twake-group-organization-status-attribute` (default `twakeOrgStatus`),

package/docs/usage/plugins/integrations/scim.md

@@ -309,6 +309,16 @@ mapping contains an entry with `scim: "department"`; otherwise the server return
 `400 invalidFilter`. Same for PATCH: operations on unmapped paths produce
 `400 invalidPath`.
 
+A User or Group body is checked against RFC 7643 before anything is written
+and before any hook reads it: `userName`, `displayName` and `id` are
+strings; a simple attribute takes a string, a number or a boolean, or a list
+of them; a complex attribute takes an object whose sub-attributes are scalars
+(or, for a reference such as `manager`, an object whose `value` is one); a
+multi-valued complex attribute such as `emails` takes a list of objects whose
+`value` is a scalar. Anything else is answered
+`400 invalidValue`, as is a PATCH operation that is not an object or whose
+`op` is not a string.
+
 A PATCH `add`, or a `remove` naming values, changes only the values it names:
 values the caller's read did not show, such as group members an
 `ldapsearchfilter` hides, stay. Two PATCHes changing different values of
@@ -369,7 +379,8 @@ via `escapeLdapFilter()` — no LDAP injection is possible.
 | `a eq "x" and b eq "y"`          | `(&(a=x)(b=y))`                           |
 | `not (a eq "x")`                 | `(!(a=x))`                                |
 
-Unknown SCIM attributes raise `400 invalidFilter`.
+Unknown SCIM attributes raise `400 invalidFilter`, as does a filter nested
+more than 32 levels deep (a parenthesis and a `not (` each count one).
 
 ## Pagination
 

package/docs/usage/plugins/integrations/spaces.md

@@ -249,7 +249,7 @@ A space reads, strongest role first:
 The plugin loads [groups](groups.md), and reads its options for the
 organization's users, groups and organization entry.
 
-- `--twake-space-base`: required, with `{org}`.
+- `--twake-space-base`: required, holding `{org}` once.
 - `--twake-space-class` (default `top,twakeSpace`): the classes of a space
   created.
 - `--twake-space-display-name-attribute` (default `twakeDisplayName`).

package/docs/usage/plugins/ldap/enterprise-rules.md

@@ -119,7 +119,10 @@ whenever the link changes. Mark the path `generated` so a client cannot set it.
 
 `5GB`, `500 MB`, `2KB` and `2048` all become a number of bytes, with decimal
 multipliers (1 GB = 10⁹ bytes) as mail servers count them. The same conversion
-applies to creations and to updates.
+applies to creations and to updates. A size above 2⁵³ − 1 bytes is refused
+(400), since its number of bytes would be rounded. A schema `number` or
+`integer` refuses a whole number beyond 2⁵³ on its own, whatever the type;
+see [what a value must look like](../../../client-development/schemas/README.md#what-a-value-must-look-like).
 
 ### Server-owned defaults
 
@@ -144,6 +147,12 @@ An `accountExpiry` attribute must not carry a date already past. The comparison
 is against the start of the current day, so scheduling something for today is
 allowed.
 
+The date is an LDAP generalized time, read as written: the year keeps its
+four digits (`0029123123` is a date of year 29, not 1929), and a leap second
+(`20991231235960Z`) is the instant that follows the day. The zone is `Z` or a
+difference of hours and minutes from UTC (`+00`, `+02`, `-0530`, `+14:00`); a
+value past 23 hours or 59 minutes is answered 400 as invalid.
+
 ### Deletion and references
 
 ```json

package/docs/usage/plugins/ldap/flat-generic.md

@@ -451,6 +451,10 @@ Content-Type: application/json
 }
 ```
 
+The identifier may also be the whole DN of the entry, in the entity's
+branch: `"uid": "uid=Smith\\,John,ou=users,dc=example,dc=com"` creates the
+entry `Smith,John`, whose DN spells the name with its escapes.
+
 ### Modify Entry
 
 ```bash

package/docs/usage/plugins/ldap/raw.md

@@ -181,6 +181,22 @@ Site-specific attributes are added with `--ldap-raw-hidden-attribute`, which sta
 --ldap-raw-hidden-attribute twakeApiKey --ldap-raw-hidden-attribute employeeNumber
 ```
 
+A hidden attribute is resolved to its directory type, so the type's OID and
+every alias it declares are hidden too — asking for `2.5.4.35` or
+`homePhone` does not serve `userPassword` or a configured
+`homeTelephoneNumber`. A search filter that tests a hidden type, at any
+depth and under any of its names, is refused with a 400: the search runs with
+the service account's rights, so leaving it through would answer the same
+question one match at a time. An assertion on a supertype of a hidden type is
+refused as well, since the directory evaluates an attribute's subtypes. An
+extensible match without an attribute (`(:octetStringMatch:=…)`) runs over
+every attribute and is refused too while attributes are hidden.
+
+When the directory schema cannot be read, an entry read or a search is
+refused with a 503 rather than answered with only the configured names
+compared, which could serve an alias or an OID. The root DSE still answers:
+it carries no entry values and is how a client discovers the schema.
+
 Note that hiding an attribute here keeps it out of the API, not out of the directory: an account able to bind to LDAP directly still reads it. This is a guard against casual exposure through the browsing UI, not an access control — use [authz-per-branch](../auth/authz-per-branch.md) or directory ACLs for that.
 
 ## Security
@@ -189,7 +205,7 @@ Access is restricted in three independent layers:
 
 1. **Exposed bases** — any DN outside `--ldap-raw-base` is refused with a 403, whatever the caller's rights.
 2. **Authorization hooks** — every entry read, children listing and search goes through `server.ldap`, so the authorization plugins ([authz-per-branch](../auth/authz-per-branch.md), authz-dynamic, …) apply exactly as on the high-level APIs.
-3. **Hidden attributes** — credential attributes, plus anything in `--ldap-raw-hidden-attribute`, are removed from every response, including searches. See [Hidden attributes](#hidden-attributes).
+3. **Hidden attributes** — credential attributes, plus anything in `--ldap-raw-hidden-attribute`, are removed from every response, including searches, under every name their type answers to; a filter that tests one is refused with a 400. See [Hidden attributes](#hidden-attributes).
 
 Two exceptions, both deliberate: the **root DSE** and the **schema** are read with the service account, not with the caller's rights. They are directory metadata and carry no user data; reading them with a restricted account would leave the UI unable to name and type attributes. Do not expose this plugin publicly if your directory publishes sensitive information in its root DSE.