ldap-rest 1.2.0 → 1.3.0

package/docs/client-development/schemas/README.md

@@ -66,7 +66,7 @@ A complete schema consists of two main sections: entity metadata and attribute d
     },
     "mail": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
       "required": false,
       "role": "primaryEmail"
     },
@@ -74,7 +74,7 @@ A complete schema consists of two main sections: entity metadata and attribute d
       "type": "array",
       "items": {
         "type": "string",
-        "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+        "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
       },
       "required": false,
       "role": "emailAliases"
@@ -197,7 +197,7 @@ Simple text values.
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
     "required": false,
     "role": "primaryEmail"
   },
@@ -237,7 +237,7 @@ Multi-valued attributes containing multiple items of the same type.
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
     },
     "required": false,
     "role": "emailAliases"
@@ -338,19 +338,20 @@ Complete reference for all attribute properties.
 
 ### Attribute Properties Table
 
-| Property   | Type            | Applies To          | Description                                                                           | Example                             |
-| ---------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
-| `type`     | string          | All                 | `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`, `"boolean"`, `"date"`    | `"string"`                          |
-| `required` | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
-| `fixed`    | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
-| `role`     | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
-| `test`     | string/regex    | String, Array items | Regular expression for validation                                                     | `"^[a-zA-Z0-9._-]{1,255}$"`         |
-| `branch`   | string[]        | Pointer             | LDAP branches where referenced entries exist                                          | `["ou=users,dc=example,dc=com"]`    |
-| `ui`       | object          | Pointer             | UI configuration for pointer selection (future feature)                               | `{}`                                |
-| `hint`     | text            | String, Array items | What a valid value looks like, shown under the field and quoted in refusals           | `"Expected pattern 999 9999"`       |
-| `group`    | text            | All                 | Form section the attribute is shown in                                                | `"Mailbox Settings"`                |
-| `default`  | any             | All                 | Default value for new entries                                                         | `["top", "person"]`                 |
-| `items`    | object          | Array               | Schema for array element validation                                                   | `{"type": "string", "test": "..."}` |
+| Property    | Type            | Applies To          | Description                                                                           | Example                             |
+| ----------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
+| `type`      | string          | All                 | `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`, `"boolean"`, `"date"`    | `"string"`                          |
+| `required`  | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
+| `fixed`     | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
+| `role`      | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
+| `test`      | string/regex    | String, Array items | Regular expression for validation                                                     | `"^[a-zA-Z0-9._-]{1,255}$"`         |
+| `maxLength` | number          | String, Array items | Longest value accepted, in characters; a longer one is refused before `test` (4096)   | `255`                               |
+| `branch`    | string[]        | Pointer             | LDAP branches where referenced entries exist                                          | `["ou=users,dc=example,dc=com"]`    |
+| `ui`        | object          | Pointer             | UI configuration for pointer selection (future feature)                               | `{}`                                |
+| `hint`      | text            | String, Array items | What a valid value looks like, shown under the field and quoted in refusals           | `"Expected pattern 999 9999"`       |
+| `group`     | text            | All                 | Form section the attribute is shown in                                                | `"Mailbox Settings"`                |
+| `default`   | any             | All                 | Default value for new entries                                                         | `["top", "person"]`                 |
+| `items`     | object          | Array               | Schema for array element validation                                                   | `{"type": "string", "test": "..."}` |
 
 A _text_ is a plain string or a map keyed by language tag,
 `{ "en": "Mailbox Settings", "fr": "Paramètres de messagerie" }`, picked as
@@ -378,16 +379,40 @@ answers, one value where the attribute holds one, can be sent back as is;
 two values or more for a single-valued attribute are refused. Each element
 of an `array` follows `items.type`, text without `items`. A `number` or
 `integer` is a JSON number or its text (`42`, `"42"`), a `boolean` a JSON
-boolean or the directory's `TRUE` / `FALSE`; anything else for them, and
+boolean or the directory's `TRUE` / `FALSE`. A JSON number is judged on the
+text written for it, what the directory is sent: `1e21` and `1e-7` are
+written `1e+21` and `1e-7`, so they are refused like that text, and a whole
+number beyond 2⁵³ is refused whatever the type, as the JSON parser has
+already lost its digits. Anything else for them, and
 anything but text for a `string`, `date` or `pointer`, is refused; an
 attribute with `normalize` takes any text, read after validation. In a
 `replace`, `null` or `[]` clears an attribute; in an `add` or on a creation
-they are refused as no value. A `delete` naming the attribute, or naming it
-with no value, removes it, unless it is `required`; naming values removes
-those, every value it holds included, as the server does not read what
-remains, and `''` names no value. An empty string sent as a value is
-checked against `test`, refused for a pointer, and missing for a `required`
-attribute. Every refusal answers 400 with the attribute's name.
+they are refused as no value when the schema declares the attribute. A
+`null` under a name the schema does not declare — and, for an entity without
+a schema, under any name — is dropped from a creation and from an `add`, as
+if the key were left out, and clears the attribute in a `replace`. A
+`delete` naming the attribute, or naming it with no value, removes it,
+unless it is `required`; naming values removes those, every value it holds
+included, as the server does not read what remains, and `''` names no
+value. An empty string sent as a value is checked against `test`, refused
+for a pointer, and missing for a `required` attribute. Every refusal answers
+400 with the attribute's name.
+
+#### What an attribute may be called
+
+A name is read as the directory reads it: case and the `;binary` option do
+not change the attribute it names, so `Cn`, `CN` and `cn;binary` all name
+`cn`. Each key the schema declares is written under the schema's spelling —
+`Cn` becomes `cn`, `L;binary` becomes `l;binary` — before any check, so that
+a `required` attribute counts as present wherever it was sent, and a `fixed`
+one is written once, at its default. The attribute's type is read the same
+way when a value is converted, so a boolean sent as `pwdReset;binary` is
+written `TRUE`.
+
+Two keys of an entry or of one part of a change naming one attribute are
+refused; the option does not make them two, so `l` and `l;binary` are
+refused together. A name the schema does not declare is left as sent, and a
+strict schema refuses it.
 
 Every entity route applies these rules; `test/lib/entitySchema.contract.test.ts`
 asserts them on a flat entity, a group and an organization alike. In the
@@ -451,7 +476,10 @@ Assigns semantic meaning to attributes for special handling by the application.
 
 #### `test` (Optional)
 
-Regular expression pattern for validating attribute values.
+Regular expression pattern for validating attribute values. The value is
+judged only up to its attribute's length: see
+[`maxLength`](#maxlength-optional) below, which a deployment writing its own
+pattern should read.
 
 ```json
 {
@@ -461,7 +489,7 @@ Regular expression pattern for validating attribute values.
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
   }
 }
 ```
@@ -474,7 +502,38 @@ Regular expression pattern for validating attribute values.
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
+    }
+  }
+}
+```
+
+#### `maxLength` (Optional)
+
+Longest value, in UTF-16 code units (what `.length` counts, so an emoji or an
+accented letter outside the basic plane counts as two), accepted before `test`
+runs on it. A value past
+it is refused with 400, and the pattern never reads it — whether or not it
+would have matched. On an array, `maxLength` on the attribute governs every
+item; one declared under `items` is read only when the attribute declares
+none. It is a positive whole number of characters: the server refuses to load
+a schema where it is not.
+
+A pattern is written for values of its attribute, not for a payload of any
+size: handed several kilobytes, a pattern whose parts overlap walks the value
+in quadratic time, on the event loop that answers every other request
+meanwhile. The limit keeps the pattern within what it was written for. It is
+**4096** unless the schema says otherwise; an attribute holding longer values
+— a description, a public key — declares its own.
+
+```json
+{
+  "sshPublicKey": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "maxLength": 16384,
+      "test": "^[^\\r\\n]*$"
     }
   }
 }
@@ -594,7 +653,7 @@ Email-related roles help applications handle email addresses consistently across
 {
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
     "required": false,
     "role": "primaryEmail"
   }
@@ -609,7 +668,7 @@ Email-related roles help applications handle email addresses consistently across
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
     },
     "required": false,
     "role": "emailAliases"
@@ -686,9 +745,14 @@ Common validation patterns:
 **Email:**
 
 ```regex
-^[^@\s]+@[^@\s]+\.[^@\s]+$
+^[^@\s]+@[^@\s.]+(\.[^@\s.]+)+$
 ```
 
+The domain part holds no dot of its own: where it did, the pattern tried every
+dot as the last separator and read the value again each time — seconds for a
+value of a few kilobytes. The result is that a trailing dot (`a@b.c.`) is
+refused, where the older form accepted it.
+
 **DN (Distinguished Name):**
 
 ```regex
@@ -1045,7 +1109,7 @@ Start with the schema that most closely matches your directory type:
   "attributes": {
     "mail": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
       "required": false,
       "role": "primaryEmail"
     },
@@ -1238,7 +1302,7 @@ Use `test` patterns to enforce data quality:
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
   }
 }
 ```

package/docs/plugin-development/README.md

@@ -8,6 +8,7 @@ This guide will help you create powerful, production-ready plugins for LDAP-Rest
 - [Plugin Structure](#plugin-structure)
 - [Creating Your Plugin](#creating-your-plugin)
 - [Custom Configuration Options](#custom-configuration-options)
+  - [Plugin options](./options.md)
 - [Loading Your Plugin](#loading-your-plugin)
 - [Plugin Features](#plugin-features)
 - [Configuration Best Practices](#configuration-best-practices)
@@ -59,8 +60,11 @@ export default class MyPlugin extends DmPlugin {
 
 - **this.server**: DM server instance
 - **this.config**: Complete configuration object
+- **this.options(declarations)**: Values of the options the plugin declares,
+  typed and checked, see [plugin options](options.md)
 - **this.logger**: Winston logger instance
-- **this.registeredHooks**: Access to global hook registry
+- **this.hookBus**: The server's hooks: chain, notify and wait on them, see
+  [hooks](hooks.md#the-bus)
 - **this.fetch**: `fetch` timed into the
   [outbound metrics](../usage/operations.md#metrics) under the plugin's
   name; the lint refuses a bare `fetch` or `node-fetch` under `src`, and a
@@ -272,99 +276,15 @@ npx ldap-rest
 
 ## Custom Configuration Options
 
-LDAP-Rest automatically accepts and stores any unknown command-line options in the config object. This allows your plugin to define custom configuration without modifying core files.
+A core plugin declares its options next to its code, in a
+`<plugin>.options.ts` file, and reads them through `this.options()` with their
+types, defaults and checks. See [plugin options](options.md).
 
-### How It Works
-
-1. **Command-line option format**: `--option-name value`
-2. **Converted to config key**: `option_name` (dashes become underscores)
-3. **Environment variable format**: `DM_OPTION_NAME` (uppercase with underscores)
-4. **Access in plugin**: `this.config.option_name`
-
-### Single Value Options
-
-```bash
-# Command line
-npx ldap-rest \
-  --webhook-url https://example.com/webhook \
-  --webhook-timeout 5000 \
-  --webhook-retry true
-
-# Environment variables
-export DM_WEBHOOK_URL=https://example.com/webhook
-export DM_WEBHOOK_TIMEOUT=5000
-export DM_WEBHOOK_RETRY=true
-```
-
-In your plugin:
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Access custom options (converted to snake_case)
-  const url = this.config.webhook_url;        // string
-  const timeout = this.config.webhook_timeout; // string (convert if needed)
-  const retry = this.config.webhook_retry;     // string 'true' (convert if needed)
-
-  // Type conversion
-  const timeoutNum = parseInt(timeout as string || '3000');
-  const retryBool = (retry as string) === 'true';
-}
-```
-
-### Multiple Value Options
-
-Repeat the same option multiple times to create an array:
-
-```bash
-# Command line
-npx ldap-rest \
-  --allowed-domain example.com \
-  --allowed-domain test.com \
-  --allowed-domain dev.com
-
-# Environment variable (comma or semicolon separated)
-export DM_ALLOWED_DOMAINS=example.com,test.com,dev.com
-```
-
-In your plugin:
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Access as array (note: singular becomes plural in config key)
-  const domains = this.config.allowed_domain as string[];
-  // or sometimes stored as: this.config.allowed_domains
-
-  this.logger.info(`Allowed domains: ${domains.join(', ')}`);
-}
-```
-
-### Configuration Priority
-
-Values are resolved in this order (later overrides earlier):
-
-1. **Default value** in your plugin
-2. **Environment variable** (`DM_OPTION_NAME`)
-3. **Command-line argument** (`--option-name`)
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Provide defaults for optional configuration
-  const webhookUrl = this.config.webhook_url || 'http://localhost:8080/webhook';
-  const webhookTimeout = parseInt(this.config.webhook_timeout as string || '3000');
-  const maxRetries = parseInt(this.config.max_retries as string || '3');
-
-  // Validate required configuration
-  if (!this.config.webhook_secret) {
-    throw new Error('--webhook-secret is required for authentication');
-  }
-}
-```
+A plugin outside the repository cannot add to `src/config/args.ts` yet. It keeps
+reading `this.config.<name>`: LDAP-Rest accepts and stores unknown
+`--option-name value` pairs under `option_name`, with `--option-name` and
+`DM_OPTION_NAME` overriding in that order. See
+[configuration](../usage/configuration.md#environment-variables).
 
 ---
 
@@ -684,7 +604,15 @@ hooks: Hooks = {
 
 ### Exposing API Endpoints
 
-Create REST API endpoints for your plugin. **Important:** Always use the `asyncHandler` wrapper for async routes to ensure errors are properly handled and don't crash the server.
+Declare routes with [`defineRoute`](routes.md): it types and validates the
+request (`params`, `query`, `body`), answers a failing request with a 400
+naming the paths at fault, and records the route for the OpenAPI document.
+The `asyncHandler` form below remains for routes that have not been migrated
+yet.
+
+Create REST API endpoints for your plugin. Always use the `asyncHandler`
+wrapper for async routes, so that errors are properly handled and do not
+crash the server.
 
 ```typescript
 import DmPlugin, { asyncHandler } from '../../abstract/plugin';
@@ -791,6 +719,29 @@ app.get(
 );
 ```
 
+**Wrapping an error keeps its answer:**
+
+Wrap with `cause` rather than in the message alone. The status and the class
+of what was thrown are read through the chain, so a refusal stays a 403 and
+a timeout a 504 wherever it surfaces:
+
+```typescript
+// ✅ GOOD: the refusal keeps its 403 when it reaches the client
+throw new Error(`Failed to add group ${dn}: ${String(err)}`, { cause: err });
+
+// ❌ BAD: a 403 becomes a 500, and its message is all that is left
+throw new Error(`Failed to add group ${dn}: ${String(err)}`);
+```
+
+**Refusing a caller:**
+
+An authorization plugin throws `AuthzRefusedError`, whose message is for the
+operator: it names the model and the branch it judged. The client is told
+`AUTHZ_REFUSED` with `code: "forbidden"` instead, whatever a plugin wrapped
+it in on the way. A refusal that is not an authorization plugin's is any
+`ForbiddenError`, answered with its own message; `isAuthzRefusal(err)` tells
+the two apart.
+
 **Custom error handling:**
 
 ```typescript

package/docs/plugin-development/dependencies.md

@@ -27,7 +27,7 @@ overrides builds a second instance, and it needs a name of its own.
 ### Hook Dependencies
 
 **Hook Providers**: Plugins that implement hooks (via `hooks: Hooks = { ... }`)
-**Hook Consumers**: Plugins that call hooks (via `runHook()` or `launchHooks()`)
+**Hook Consumers**: Plugins that raise hooks (via `this.hookBus`)
 
 ## Complete Dependency Graph
 
@@ -601,10 +601,10 @@ refused before a plugin judges its content, or replaces it.
 2. Returns modified data to next plugin
 3. Last plugin's return value is used
 
-For non-chained hooks:
+For notified hooks, see [hooks](hooks.md#the-bus):
 
-- All hooks execute in parallel
-- Order doesn't matter
+- All hooks run one after the other, in load order
+- A failing one is logged and the next still runs
 
 **Example**: `ldapdeleterequest` chain
 
@@ -642,11 +642,16 @@ export default class MyPlugin extends DmPlugin {
 
 ### Providing Hooks
 
+A hook is declared in `src/hooks.ts` before anything raises it, and raised
+through the bus of the kind it is, see [hooks](hooks.md#the-bus):
+
 ```typescript
 export default class MyPlugin extends DmPlugin {
   async someMethod() {
-    // Fire a hook for other plugins to consume
-    await this.server.launchHooks('myCustomHook', [param1, param2]);
+    // Thread a value through the subscribers of a chained hook
+    value = await this.hookBus.chain('ldapsearchopts', value);
+    // Tell the subscribers of a notified one, without waiting for them
+    this.hookBus.notify('ldapadddone', dn, entry, changeContext(req));
   }
 }
 ```

package/docs/plugin-development/hooks.md

@@ -1,34 +1,143 @@
 # 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
+- **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 +147,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 +175,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).