ldap-rest 1.2.1 → 2.0.0

package/docs/plugin-development/hooks.md

@@ -1,34 +1,144 @@
 # Core hooks
 
-The hooks a plugin can register. Their arguments and return values are
-those typed in [hooks.ts](../../src/hooks.ts), which is the reference.
+Hooks are how plugins talk to each other. Each one is declared in
+[hooks.ts](../../src/hooks.ts), which is the reference for the arguments it
+gets and what it must answer; a plugin subscribing to a hook it does not
+name there does not compile.
 
-## Demo hooks
+## The bus
 
-- **hello**: called by [helloworld demo plugin](../../src/plugins/demo/helloworld.ts)
+`this.hookBus` (or `server.hookBus`) is how a plugin raises a hook, and how a
+test waits for one. It has one method per kind of hook, told apart by what a
+subscriber answers:
 
-## [LDAP](../../src/lib/ldapActions.ts) hooks
+| Kind     | Method                                                | Subscriber                                                                                 |
+| -------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| chained  | `chain(name, value)`                                  | answers the value, changed or not                                                          |
+| notified | `notify(name, ...args)`                               | answers nothing, not awaited                                                               |
+| notified | `notifyAndWait(name, ...args)`                        | answered nothing, awaited                                                                  |
+| notified | `notifyStrict(name, ...args)`                         | as `notifyAndWait`, but a failure goes to the caller                                       |
+| any      | `has(name)`, `subscribers(name)`                      | —                                                                                          |
+| any      | `settled()`                                           | resolves once every notification so far has run                                            |
+| any      | `set`, `subscribe`, `insert`, `unsubscribe`, `toLast` | add a subscriber, or move one: for a test, or for a plugin changing what its base declares |
 
-- **ldapsearchopts**: called before any ldapsearch to modify search options
-- **ldapsearchresult**: called after any ldapsearch to modify search result
-- **ldapaddrequest**: called before any ldapadd
-- **ldapadddone**: launched once an ldapadd has written the entry, not awaited
-- **ldapaddafter**: awaited once an ldapadd has written the entry, before it
-  answers, see [below](#ldapaddafter)
-- **ldapmodifyrequest**: called before any ldapmodify
-- **ldapdeleterequest**: called before any ldapdelete
-- **ldaprenamerequest**: called before any ldap rename/modifyDN operation
-- **ldapmodifyend**, **ldapdeleteend**, **ldaprenameend**: launched once a
-  modify, delete or rename is over, whatever became of it, see
-  [below](#ldapmodifyend-ldapdeleteend-ldaprenameend)
+A chained hook is handed its arguments as one value, a tuple when it has
+several. A notified hook is handed them one by one: its subscriber is
+`(dn, entry, context) => …`, never `([dn, entry], context) => …` — that form
+still compiles, the parameters being bivariant, but then reads the DN's first
+character as the DN.
+
+- **Chained.** The value goes from one subscriber to the next, each getting
+  what the one before answered; the last answer is the result. A subscriber
+  that throws stops the chain and the error travels up: a refusal is a
+  refusal. Several values are passed as one tuple.
+- **Notified.** Subscribers run one after the other, outside the request
+  that caused the write, and are told what happened and was judged: they
+  react as the server — synchronizing, publishing, keeping invariants —
+  whoever asked. `notify` does not wait for them and never fails: the write
+  they react to is done, and a failing subscriber is logged, with its plugin
+  and hook, and counted in the [hook failure
+  metrics](../usage/operations.md#metrics), then the next one still runs.
+- **`notifyStrict`** is for the rare subscriber whose failure is part of the
+  answer: a logout token reaches the provider only once what it closes is
+  recorded, so the library answers 400 and the provider retries. Every
+  subscriber runs even when one fails, and the first failure is raised once
+  they all have.
+
+A test that would otherwise sleep waits instead:
+
+```ts
+// One hook's subscribers
+await server.hookBus.notifyAndWait('ldapadddone', dn, entry, {});
+// or whatever the write under test started
+await server.hookBus.settled();
+```
+
+## Hooks
+
+<!-- hooks: generated from src/hooks.ts, do not edit by hand -->
+
+- **hello**: raised by the [demo plugin](../../src/plugins/demo/helloworld.ts) for `/hello`, answered by the demo plugins
+- **ldapsearchopts**: chained before any search, with its options
+- **ldapsearchrequest**: chained before any search, with `[base, options, request]`; an authorization plugin refuses by throwing
+- **ldapsearchresult**: chained after any search, with its result, before it is cached; for a paged search, when the first page is read
+- **ldapsearchfilter**: chained on the result of a search after the cache, once per page, with `[result, request, options]`, to drop what the caller may not see
+- **ldapaddrequest**: chained before any add, with `[dn, entry, request]`
+- **ldapadddone**: notified once an add has written the entry, with the DN, the entry and the context, one by one; not awaited
+- **ldapaddafter**: notified once an add has written the entry, before it answers, with the DN, the entry and the context, one by one, see [below](#ldapaddafter)
+- **ldapmodifyrequest**: chained before any modify, with `[dn, changes, op, request]`
+- **ldapmodifydone**: notified once a modify is written, with the DN, the changes, the operation number and the context, one by one
+- **ldapmodifyend**: notified once a modify is over, whatever became of it, and its done subscribers have returned
+- **ldapdeleterequest**: chained before any delete, with `[dn, request]`
+- **ldapdeletedone**: notified once a delete is written, with the DN and the context, one by one
+- **ldapdeleteend**: notified once a delete is over, whatever became of it, and its done subscribers have returned
+- **ldaprenamerequest**: chained before any rename or move, with `[dn, newDn, request]`
+- **ldaprenamedone**: notified once a rename or a move is written, with the DN, its new DN and the context, one by one
+- **ldaprenameend**: notified once a rename is over, whatever became of it, and its done subscribers have returned
+- **oidcsessionvalid**: chained with the claims of a session and the verdict so far, see [the OpenID Connect page](../usage/plugins/auth/openid-connect.md)
+- **oidclogouttoken**: notified with the claims of a session a logout token or `/logout` ends
+- **oidclogin**: notified with the claims of a session just established
+- **ldapgroupvalidatenew**: chained before a group is created, with `[dn, entry]`
+- **ldapgroupadd**: chained before a group is added, with `[dn, entry]`
+- **ldapgroupadddone**: notified once a group is added, with the DN and the entry, one by one
+- **ldapgroupvalidatechanges**: chained before a group is modified, with `[dn, changes]`
+- **ldapgroupmodify**: chained before a group is modified, with `[dn, changes, op]`
+- **ldapgroupmodifydone**: notified once a group is modified, with the DN, the changes and the operation number, one by one
+- **ldapgrouprename**: chained before a group is renamed, with `[dn, newDn]`
+- **ldapgrouprenamedone**: notified once a group is renamed, with the DN and its new DN, one by one
+- **ldapgroupdelete**: chained before a group is deleted, with its DN
+- **ldapgroupdeletedone**: notified once a group is deleted, with its DN
+- **ldapgroupaddmember**: chained before members are added, with `[cn, members]`
+- **ldapgroupdeletemember**: chained before a member is removed, with `[cn, member]`
+- **ldapgroupvalidatemembers**: chained before a member is added, to judge the members, with `[dn, members]`
+- **\_ldapgrouplist**: chained around the list of groups, internal to the groups plugin
+- **onLdapEntryChange**: notified with the entry before and after any write, and who made it
+- **onLdapChange**: notified with the attributes a write changed
+- **onLdapMailChange**: notified with the mail before and after a change, or with no new mail for a delete
+- **onLdapAliasChange**: notified with the mail and the aliases before and after a change
+- **onLdapQuotaChange**: notified with the mail and the quota before and after a change
+- **onLdapForwardChange**: notified with the mail and the forwards before and after a change
+- **onLdapDisplayNameChange**: notified with the name before and after a change
+- **onLdapDriveQuotaChange**: notified with the drive quota before and after a change
+- **externaluserentry**: chained before an external member is created, with `[dn, entry]`
+- **externaluseradded**: notified once an external member is created, with the DN and the entry, one by one
+- **beforeAuth**: chained on a request before it is authenticated, with `[request, response]`
+- **afterAuth**: chained on a request once it is authenticated, with `[request, response]`
+- **getOrganisationTop**: chained before the top organization is answered, with `[request, entry]`
+- **scimusercreate**: chained before a SCIM user is created, with `[user, request]`
+- **scimusercreatedone**: notified once a SCIM user is created
+- **scimuserupdate**: chained before a SCIM user is replaced, with `[id, user, request]`
+- **scimuserupdatedone**: notified once a SCIM user is replaced, with id, user (one by one)
+- **scimuserdelete**: chained before a SCIM user is deleted, with `[id, request]`
+- **scimuserdeletedone**: notified once a SCIM user is deleted, with its id
+- **scimgroupcreate**: chained before a SCIM group is created, with `[group, request, base]`
+- **scimgroupcreatedone**: notified once a SCIM group is created
+- **scimgroupupdate**: chained before a SCIM group is replaced, with `[id, group, request]`
+- **scimgroupupdatedone**: notified once a SCIM group is replaced, with id, group (one by one)
+- **scimgroupdelete**: chained before a SCIM group is deleted, with `[id, request]`
+- **scimgroupdeletedone**: notified once a SCIM group is deleted, with its id
+- **scimbulkdone**: notified once a SCIM bulk request is answered
+- **twakedeletionreplay**: notified with the DN, the entry and the context, one by one when a delete asks of an entry that is already a tombstone
+
+<!-- /hooks -->
+
+## Flat entities
+
+A plugin built on `LdapFlat` (`--ldap-flat-schema`) raises one set of hooks
+per entity: `ldap${entity.name}` followed by the suffix of the shared hook of
+the same kind — `add` and `adddone`, `modify` and `modifydone`, `rename` and
+`renamedone`, `delete` and `deletedone`, with the same arguments — plus
+`{prefix}move` before an entry is moved, followed by `onLdapChange` as a
+modify is. A plugin watching one declares it beside its other hooks.
+
+## LDAP write hooks
 
 ### ldapaddafter
 
 For what must follow an add within the same request, such as provisioning
 the account the entry describes.
 
-- Subscribers get `[dn, entry]` and the change context, as `ldapadddone`
-  does. They run one after the other, and `add()` answers once the last has
+- Subscribers get the DN, the entry and the change context, one by one, as
+  `ldapadddone` does. They run one after the other, and `add()` answers once the last has
   returned.
 - An error is logged and goes no further: the add has succeeded, and the
   next subscriber still runs. A subscriber that can fail owns its repair
@@ -38,7 +148,8 @@ the account the entry describes.
   empty. Some of these follow an API call all the same, so select entries by
   their DN or attributes rather than by an empty context.
 - The entry is the one submitted, after `ldapaddrequest`, not what the
-  directory holds: no operational attributes, and the password as given.
+  directory holds: no operational attributes, and a `Buffer` value — a
+  password sent that way — read as a string.
 - `ldapadddone` and `onLdapEntryChange` fire whatever this hook does, and in
   no set order with it: an add event may or may not include what a
   subscriber here wrote.
@@ -65,8 +176,17 @@ never reaches its "done" hook; its "end" hook fires all the same.
   its `ldaprenamedone` runs outside any operation, even when a request hook
   made it.
 
-## [onChange](../usage/plugins/ldap/on-change.md) hooks
+## onLdapChange
 
 - **onLdapEntryChange**: called after any write, with the entry before and
-  after it, and who made it
-- **onLdapChange**, **onLdapMailChange**…: derived from it
+  after it, and who made it.
+- **onLdapChange**, **onLdapMailChange**…: derived from it, and the
+  attribute ones fire only while the entry has the attribute configured for
+  them. A delete fires `onLdapEntryChange`, `onLdapChange` and
+  `onLdapMailChange` only.
+
+## Ordering
+
+Hooks run in the order their plugins loaded, but for the request hooks of
+authorization plugins, which run before every other plugin's, see
+[dependencies](dependencies.md#hook-execution-order).

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,136 @@
+# 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.
+
+### Deprecating an option
+
+Rename an option by giving the old name as an alias: the parser still reads
+it, and the server warns once at startup. Keep the alias for two minor
+releases, as [CONTRIBUTING.md](../../CONTRIBUTING.md#deprecating-a-published-contract)
+requires.
+
+```typescript
+export const exampleOptions = defineOptions({
+  example_url: opt.string({
+    env: 'DM_EXAMPLE_URL',
+    aliases: ['example-uri'],
+    envAliases: ['DM_EXAMPLE_URI'],
+  }),
+});
+```
+
+A CLI alias takes one value per occurrence, as the singular form does, and an
+array option's plural form has no alias: renaming it is a breaking change. An
+environment alias is read when `env` is unset, or empty for a type where an
+empty value means nothing, and only for a non-array option when its canonical
+CLI name is absent; an array option combines the environment value with the
+CLI one, so its alias is still read.
+
+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                            |
+| `aliases`    | Former CLI names still accepted, without the leading `--`             |
+| `envAliases` | Former environment variables still accepted, read when `env` is unset |
+
+## 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 their aliases, and `options()` reads a declared
+`env` variable or a deprecated CLI alias the parser did not carry, warning at
+startup for the alias as it does for a core option. 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/services.md

@@ -0,0 +1,95 @@
+# Plugin services
+
+A plugin sometimes needs what another plugin holds: the group operations, the
+entity schemas, the trash. A service is a typed interface a plugin provides
+under a token, and another plugin reaches with `this.service(token)`.
+
+The token carries the interface. The compiler checks that an instance bound
+with `with()` answers it, and gives a consumer the type it declared. Whether a
+provider exists is a runtime question: a plugin that stops declaring the token
+still compiles, and its consumers get `null` and a warning. The plugin
+registry name stays what it is for: loading a plugin and naming it in the
+logs.
+
+## Declaring a service
+
+Put the token and its interface in a module both sides import — a plugin
+family's own service in its own module. A service shared between families is
+declared in `src/lib/services/` and re-exported from `ldap-rest/plugin`, one
+of the package's entry points; a module under `src/lib/` has no export path of
+its own.
+
+```typescript
+import { serviceToken } from 'ldap-rest/plugin';
+
+export interface GroupsApi {
+  listGroups(): Promise<string[]>;
+}
+
+export const GroupsService = serviceToken<GroupsApi>('groups');
+```
+
+Declare a token once. The object is the registry key; calling `serviceToken`
+again under the same name declares another service, not the same one. The name
+only identifies it in the logs.
+
+## Providing a service
+
+Bind the plugin instance to each token it provides:
+
+```typescript
+import DmPlugin from 'ldap-rest/plugin';
+
+export default class LdapGroups extends DmPlugin {
+  name = 'ldapGroups';
+  provides = [GroupsService.with(this)];
+
+  async listGroups(): Promise<string[]> {
+    /* … */
+  }
+}
+```
+
+`with(this)` is checked by the compiler: an instance that does not answer the
+interface does not compile. A plugin can provide several services. A service
+is registered once its plugin's registration completes — after `api()` and
+the hooks — so a consumer loaded afterwards finds it, and a provider does not
+find its own service there. A plugin needing another one declares it in
+[`dependencies`](dependencies.md#explicit-dependencies) so that it loads
+first.
+
+The first provider to register wins. A second one offering the same token is
+ignored and named in a warning: which one answered would otherwise depend on
+load order. Loading the same module twice under two names gives two instances
+but one module-level token, so the second instance cannot provide it either.
+
+When a host registers a plugin after startup, its `assertComposition` runs
+before the service is registered, so a provider does not find its own service
+there; the configuration's plugins are all registered before their
+`assertComposition` runs.
+
+## Consuming a service
+
+```typescript
+const groups = this.service(GroupsService);
+if (!groups) {
+  // Nothing provides it: the plugin skips the feature it would serve
+  return;
+}
+await groups.listGroups();
+```
+
+`service()` answers the provided instance, or `null` when nothing provides the
+token. It logs one warning per plugin and service rather than one per call. A
+plugin that cannot work without a service declares the provider in
+`dependencies`, checks the answer in `assertComposition`, and throws naming the
+service — that stops the server at startup instead of leaving a feature
+silently absent. A constructor runs before the dependencies load, so it cannot
+be the place for that check.
+
+The registry belongs to the server and is shared by the views `withConfig`
+builds for plugins loaded with overrides. It has no removal: a plugin
+registers once and keeps its services for the life of the server.
+
+`this.requirePlugin(name)` remains for a plugin whose interface is not yet
+declared as a service; new code reaches another plugin through a token.

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