ldap-rest 1.2.1 → 1.3.0

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

package/docs/usage/upgrading.md

@@ -4,6 +4,200 @@ What to check before deploying, newest first. Only releases that need a
 decision or a configuration change appear here; see the
 [CHANGELOG](../../CHANGELOG.md) for everything else.
 
+## From 1.2.1
+
+### A plugin written against the old hooks API
+
+**Who is affected:** a deployment loading a plugin built outside this
+repository that calls `launchHooks` / `launchHooksChained`, or subscribes
+to a `*done` hook with its arguments packed in one tuple.
+
+Hooks are raised through `this.hookBus`, and every hook is declared in
+`src/hooks.ts`: a plugin raising or subscribing to a hook the server does
+not declare no longer compiles. A notified hook — `ldapadddone`,
+`ldapaddafter`, `ldapmodifydone`, `ldaprenamedone`, `ldapgroupadddone`,
+`ldapgroupmodifydone`, `ldapgrouprenamedone`, `ldapexternaluseradded` — now
+gets its arguments one by one: `(dn, entry, context) => …`, not
+`([dn, entry], context) => …`. The packed form still compiles — parameters
+are bivariant — and then reads the DN's first character, so a plugin left
+as it was stops reacting without saying so. `ldapgroupdeletemember` threads
+`[cn, member]`, a single member DN, as it always handed one.
+
+A test waiting for a hook to land waits on `await server.hookBus.settled()`
+rather than sleeping. See [hooks](../plugin-development/hooks.md#the-bus).
+
+### A plugin with its own `options` or `optionDefinitions` member
+
+**Who is affected:** a plugin built outside this repository that declares a
+field, getter or method named `options`, or a static field named
+`optionDefinitions`.
+
+`DmPlugin` now has `options()`, which returns the values a plugin declared
+through `optionDefinitions`. Rename the plugin's own `options` member; a
+plugin that does not declare options keeps reading `this.config` as before.
+
+### A plugin extending `TwakePlugin`
+
+**Who is affected:** a plugin built outside this repository whose class extends
+`TwakePlugin`.
+
+The base constructor takes the WebAdmin URL, token and concurrency instead of
+the names of the options holding them:
+
+```ts
+import { jamesOptionsOf } from 'ldap-rest/plugin-twake-james.options';
+
+const options = jamesOptionsOf(server.config);
+super(server, {
+  url: options.james_webadmin_url,
+  token: options.james_webadmin_token,
+  concurrency: options.james_concurrency,
+  urlOption: 'james_webadmin_url',
+  tokenOption: 'james_webadmin_token',
+  concurrencyOption: 'james_concurrency',
+});
+```
+
+The three `*Option` fields only name the option in the startup error and the
+missing-token warning. `concurrency` must be a positive integer; the base
+refuses anything else, naming `concurrencyOption`.
+
+### A plugin building SCIM's exported helpers
+
+**Who is affected:** a plugin built outside this repository that constructs
+`ScimUsers`, `ScimGroups`, `ScimBulk`, `ScimDiscovery` or `BaseResolver`, or
+calls `scimBodyParser`.
+
+These take the SCIM options instead of a plain `Config`:
+
+```ts
+import { scimOptionsOf } from 'ldap-rest/plugin-scim-scim.options';
+
+const options = scimOptionsOf(config);
+```
+
+`BaseResolver` keeps its `(config, options)` form; the others take the checked
+values beside what they already require.
+
+### An invalid SCIM or Twake value
+
+**Who is affected:** a deployment setting a SCIM limit to zero or a negative
+number, giving a per-instance override of the wrong JSON type, or setting the
+James, Calendar, Drive or migration proxy concurrency to the wrong type.
+
+These options now refuse a value below 1 when the plugin loads: a zero used
+to be silently replaced by the default, and a negative value used as it was.
+Remove the option to keep the default, or give it a positive number.
+
+A per-instance override (`--plugin core/scim:name:{...}`) must also use the
+option's JSON type: `{"scim_max_results": "50"}` and `{"scim_user_base":
+null}` are refused, where the quoted number used to be coerced and the null
+treated as unset. The applicative accounts options refuse the same:
+`{"max_app_accounts": "5"}` used to be kept as the string, and
+`{"applicative_account_attribute": "cn"}` was spread into `['c', 'n']`.
+
+The James, Calendar, Drive and migration proxy concurrency used to replace a
+value that was not a number with `10`, and now refuses it. A zero or a
+negative value was already refused by `p-limit`, and the message now names
+the option. The other Twake options also refuse a value of the wrong JSON
+type in an override.
+
+A zero `--twake-group-max-page-limit`, `--twake-instance-timeout`,
+`--cloudery-workflow-poll-interval-ms` or
+`--cloudery-workflow-max-attempts` used to be replaced by the default and is
+now refused.
+
+The authentication and authorization options are checked the same way. A zero
+`--rate-limit-window-ms`, `--rate-limit-max`, `--crowdsec-cache-ttl`,
+`--authz-per-branch-cache-ttl` or `--authz-dynamic-cache-ttl` used to be
+replaced by the default and is now refused. A zero `--auth-totp-step` or
+`--auth-hmac-window` was accepted and broke the plugin — every counter was
+`Infinity`, every signature not made in the same millisecond was refused — and
+is now refused at startup. A zero `--ldap-organization-max-subnodes`,
+`--ldap-raw-max-results`, `--ppolicy-warn-days`, `--ppolicy-min-length` or
+`--bcl-retention` used to be replaced by the default and is now refused.
+
+`ConfigParser` keeps an empty string for a string option. A plugin reads the
+declared default instead when that default is not empty, as its `|| default`
+used to: `DM_COZY_ADMIN_USER=` gives `admin`, `DM_CLOUDERY_OFFER=` gives
+`b2b_twake_default`. An option whose empty value means something says so in
+its declaration (`--cozy-apps`, `--cozy-user-deleted-routing-key`,
+`--twake-instance-cozy-apps`, `--twake-instance-cozy-context`,
+`--twake-instance-cloudery-offer`) and keeps it; an option whose default is
+empty keeps the empty string.
+
+### The group member check option
+
+**Who is affected:** a deployment passing `--group-allow-unexistent-members`.
+
+That spelling was stored under a key the groups plugin never read, so it never
+disabled member validation. The option is now `--groups-allow-unexistent-members`
+and `DM_ALLOW_UNEXISTENT_MEMBERS`, which the plugin reads; the old spelling is
+gone.
+
+### A config key a plugin did not declare
+
+**Who is affected:** a plugin built outside this repository reading an option
+through `this.config.<name>` without declaring it.
+
+`Config` no longer has an index signature, so such a read does not compile.
+Declare the option with `defineOptions` and read it through `this.options()`
+(see [plugin options](../plugin-development/options.md)); the declaration also
+makes the option known to the startup report and its `env` variable read.
+
+### Node 22 or later is required
+
+**Who is affected:** a deployment running on Node 20 (end of life
+2026-04-30). A deployment of the published image is not: it is built on Node 24.
+
+`engines` declares `>=22`, and the CI runs the suite on 22, 24 and 26. Node
+20 is neither tested nor supported.
+
+### Values past 4096 characters, and an address with a trailing or empty label
+
+**Who is affected:** a deployment whose schemas accept a value longer than
+4096 characters, or an address such as `a@b.c.` or `a@b..c` in an attribute
+whose pattern came with the shipped schemas.
+
+A schema `test` pattern is no longer run on a value longer than 4096
+characters; the value is answered 400, naming the length, before the pattern
+sees it, so that a pattern cannot be made to walk several kilobytes. This
+holds for every attribute in every schema which carries a pattern, a
+deployment's own included, and none of the shipped schemas declares a longer
+limit. An attribute holding longer values declares its own `maxLength`, a
+whole number of characters, or the server refuses to load the schema:
+
+```json
+{
+  "sshPublicKey": {
+    "type": "array",
+    "items": { "type": "string", "maxLength": 16384, "test": "^[^\\r\\n]*$" }
+  }
+}
+```
+
+The address patterns shipped with the schemas no longer accept a trailing dot
+or an empty label: `a@b.c.`, `a@b..c` and `a@.b.c` are refused. Entries already holding
+such a value stay as they are; the value is refused the next time that
+attribute is written. A deployment that copied one of these patterns keeps
+its own copy, unbounded only if it declares no `maxLength`; the patterns to
+use are in the
+[schema reference](../../docs/client-development/schemas/README.md#test-optional).
+
+### A `null` under a name the schema does not declare
+
+**Who is affected:** a client sending `null` to an entity whose schema does
+not declare the attribute, or to an entity without a schema — the
+`dhcpHosts` and `dnsRecords` schemas shipped with `"strict": false` among
+them.
+
+Such a write answered 500, with nothing written. It now succeeds: the key is
+left out of a creation or an `add`, and clears the attribute in a `replace`.
+No action is required. A strict schema still answers 400 for such a name, and
+the value is written as if the key were left out, so a client relying on the
+500 to notice a misspelt attribute no longer hears about it — see
+[what a value must look like](../client-development/schemas/README.md#what-a-value-must-look-like).
+
 ## From 1.2.0 to 1.2.1
 
 ### `{org}` once in a Twake branch pattern