ldap-rest 0.11.2 → 0.13.0

package/docs/usage/plugins/integrations/lifecycle-events.md

@@ -0,0 +1,233 @@
+# Lifecycle Events
+
+`core/twake/lifecycleEvents` publishes an account's or a group's lifecycle to
+RabbitMQ from the directory write itself. REST, SCIM and any other plugin writing through
+LDAP-Rest announce the same events, with the same payloads.
+
+Which entries are accounts or groups, which attributes carry the role, the
+lock, the deletion and the members, and where each event goes are
+configuration.
+
+## Events
+
+Each event is a change of state, read from the entry before and after a write
+(`onLdapEntryChange`, from `core/ldap/onChange`). A write that changes nothing
+publishes nothing.
+
+- `created`: an entry is added. An entry added locked, as a SCIM create with
+  `active: false` does, publishes `created` then `disabled`.
+- `roleChanged`: the role attribute gets different values. Case and order are
+  ignored: `Admin` and `admin` are one role. A multi-valued role attribute is
+  compared as a set, but `$title` carries its first value only, so
+  `[x, y]` to `[x, z]` publishes `x` as both role and previous role: keep the
+  role in a single-valued attribute.
+- `disabled`: the lock attribute takes the lock value.
+- `enabled`: the lock attribute no longer holds the lock value.
+- `updated`: a target whose payload has `$changed.` sources publishes when one
+  of them changed, with those that did not left out. A target without them
+  publishes on every change of the entry.
+- `memberAdded`, `memberRemoved`: the member attribute gains or loses values.
+  The old and new lists are compared as sets, so a whole list replaced
+  publishes only the members that came or went. The group placeholder
+  (`--group-dummy-user`) is never a member here. A group created with
+  members publishes `created` only, its members in `$members`.
+- `deleted`: the entry becomes a tombstone (the deleted attribute takes the
+  deleted value), or an entry that is not a tombstone is removed.
+
+An account is locked when its lock attribute holds the lock value, by default
+the ppolicy administrative lock `000001010000Z`. Any other value, such as the
+timestamp of a ppolicy lockout after failed binds, is not a lock here.
+
+A tombstone announces nothing else: the write that makes it does not also
+publish `disabled`, later changes to it (a lock written afterwards included)
+publish nothing, and removing it publishes nothing, since its deletion was
+already announced.
+
+A publish that fails is logged as an error, and the next targets are still
+published. It never fails the write that caused it, and the event is not
+replayed: writing the same value again changes nothing, so it publishes
+nothing. With `core/twake/tombstone`, a lost `deleted` is published again by
+deleting the tombstone once more (see below); a lost `disabled`, `enabled`,
+`created` or `roleChanged` has no such path.
+
+The lock attribute is requested by name when the entry is read, so an
+operational one such as `pwdAccountLockedTime` is seen on both sides.
+
+## What is not published
+
+- A rename or a move publishes nothing. The `$dn.*` groups of the new DN may
+  then differ from the ones consumers know, and an entry moved into or out of
+  a rule's pattern publishes neither `created` nor `deleted`.
+- A tombstone cannot be restored. Clearing its deleted attribute is not a
+  supported operation: it publishes nothing, whatever else the same write
+  changes, and later changes are published again as for any account, to
+  consumers that consider it deleted.
+- A change made outside LDAP-Rest is not seen. A ppolicy lockout after failed
+  binds is written by the directory itself, and holds a timestamp rather than
+  the lock value: it publishes nothing, and neither does clearing it.
+
+## Deployments with other plugins
+
+- `core/twake/tombstone` answers a second delete of a tombstone without
+  writing anything, and fires `twakedeletionreplay`; this plugin then
+  publishes `deleted` again, with the tombstone as it is (same deletion date).
+  This explicit delete is how a `deleted` event a broker outage lost is
+  replayed.
+- `core/twake/cozyProvision` and `core/twake/clouderyProvision` publish their
+  own deletion event on `--cozy-user-deleted-routing-key`. When a `deleted`
+  rule here publishes it, set that option to `""`. Turning it off without a
+  `deleted` rule leaves no deletion event at all; keeping both publishes it
+  twice.
+- `core/ldap/trash` moves a deleted entry instead of removing it, and a move
+  made by the trash is not seen by `core/ldap/onChange`. A deletion in a
+  branch the trash watches publishes nothing.
+
+## Configuration
+
+```bash
+--plugin core/twake/lifecycleEvents \
+--twake-lifecycle-role-attribute title \
+--twake-lifecycle-lock-attribute pwdAccountLockedTime \
+--twake-lifecycle-lock-value 000001010000Z \
+--twake-lifecycle-deleted-attribute employeeType \
+--twake-lifecycle-deleted-value deleted \
+--twake-lifecycle-deleted-at-attribute roomNumber \
+--twake-lifecycle-deleted-at-format iso8601 \
+--twake-lifecycle-rules /etc/ldap-rest/lifecycle-rules.json
+```
+
+- `--twake-lifecycle-role-attribute`: empty means no `roleChanged`.
+- `--twake-lifecycle-lock-attribute`, `--twake-lifecycle-lock-value`: default
+  to `--scim-user-lock-attribute` and `--scim-user-lock-value`, so SCIM
+  `active` and the events agree; SCIM's value only goes with SCIM's
+  attribute. `pwdAccountLockedTime` defaults to `000001010000Z`; any other
+  attribute needs its value, or the server does not start, as for
+  [SCIM](scim.md).
+  Only changes written through LDAP-Rest are seen: a lockout set by the
+  directory publishes nothing.
+- `--twake-lifecycle-deleted-attribute`, `--twake-lifecycle-deleted-value`
+  (default `TRUE`, compared case-insensitively): what marks a tombstone. Empty
+  means entries are never tombstones, and only a removal publishes `deleted`.
+- `--twake-lifecycle-deleted-at-attribute`,
+  `--twake-lifecycle-deleted-at-format` (`iso8601`, the default, or
+  `generalizedTime`): the deletion date. It is always published as ISO 8601.
+- `--twake-lifecycle-member-attribute` (default `member`): the attribute
+  `memberAdded`, `memberRemoved` and member lists read.
+- `--twake-lifecycle-rules`: a JSON file, or the JSON itself.
+
+Each option has a `DM_` environment variable, for example
+`DM_TWAKE_LIFECYCLE_RULES`. The events go through `core/rabbitmq`. With rules
+configured, the server does not start without `--rabbitmq-url`, nor when
+that broker cannot be reached. An event that finds no broker later on is
+lost, and logged as an error.
+
+## Rules
+
+The rules are an array. The first rule whose `dn` regular expression matches
+the entry's DN (case-insensitively) decides what is published; an entry no
+rule matches publishes nothing.
+
+The DN is matched without spaces around its separators, and with escaped
+commas written `\2C`: `uid=a\, b, ou=users,…` is read as `uid=a\2C b,ou=users,…`,
+so `(?<id>[^,]+)` takes the whole value. A `$dn.name` group is unescaped:
+`a, b`.
+
+```json
+[
+  {
+    "dn": "^uid=(?<id>[^,]+),ou=users,dc=example,dc=com$",
+    "exchange": "accounts",
+    "payload": {
+      "id": "$dn.id",
+      "email": "$mail",
+      "domain": "$mail|domain",
+      "role": "$title",
+      "timestamp": "$now"
+    },
+    "events": {
+      "created": "account.created",
+      "roleChanged": {
+        "routingKey": "account.role.changed",
+        "payload": {
+          "id": "$dn.id",
+          "role": "$title",
+          "previousRole": "$previous.title"
+        }
+      },
+      "disabled": "account.disabled",
+      "enabled": "account.enabled",
+      "deleted": [
+        "account.deleted",
+        {
+          "exchange": "notifications",
+          "routingKey": "account.deleted",
+          "when": { "$businessCategory": "user_request" },
+          "payload": { "id": "$dn.id", "mobile": "$previous.mobile" }
+        }
+      ]
+    }
+  }
+]
+```
+
+An event takes one target or a list of them, published in order. A target is
+a routing key, or an object with:
+
+- `routingKey`
+- `exchange`: defaults to the rule's
+- `payload`: replaces the rule's `payload`
+- `when`: publish only if every source equals its value; a value starting with
+  `!` means "differs from"
+
+Payload and `when` values are sources:
+
+- `$attr`: the attribute after the write; for a removed entry, which has no
+  "after", the attribute before it
+- `$previous.attr`: the attribute before the write
+- `$dn.name`: a named group of the rule's `dn` expression
+- `$context.actor`, `$context.requestId`, `$context.source`: who made the
+  write, the request it belongs to, and the API it came through (`rest`,
+  `scim`); left out for a write no request made, such as a scheduled task
+- `$changed.attr`: the attribute after the write, only if the write changed
+  it; an attribute the write removed gives `""`
+- `$attr|domain`, `$previous.attr|domain`: what follows the `@`
+- `$now`: the current time, ISO 8601
+- anything else: the value itself
+
+`$attr` and `$previous.attr` carry the first value of a multi-valued
+attribute. A source with no value leaves its field out.
+
+A payload field can also list members, as an object with one key:
+
+- `$members`: the members after the write
+- `$added`, `$removed`: the members `memberAdded` and `memberRemoved` are about
+
+```json
+"members": { "$added": { "username": "$uid", "email": "$mail" } }
+```
+
+Each member is read once, and shaped by the object it maps to, whose
+sources are its own attributes (`$attr`) or plain values; any other source is
+refused at startup. A tombstone is left
+out, and a target whose `$added` or `$removed` is left empty publishes
+nothing. A member no longer in the directory is known by its RDN alone:
+`uid=jdoe,…` gives `{ "username": "jdoe" }` above. A group of 1,000 members
+takes 1,000 reads, one after the other, off the path of the write's
+response. A member that cannot be read, for a reason other than being gone,
+drops that target, logged as an error: a member the service account may not
+read silences every target of the group that lists its members. Every message carries
+a random AMQP `messageId`.
+
+A source can read any attribute of the entry: `$userPassword` would put the
+password hash in the message.
+
+The rules are checked at startup: a malformed one, such as a payload value
+that is not a string, stops the server with an error naming its `dn`.
+
+## Dependencies
+
+```
+core/twake/lifecycleEvents
+  ├─ requires: core/ldap/onChange
+  └─ requires: core/rabbitmq
+```

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

@@ -51,7 +51,7 @@ All SCIM endpoints sit behind the auth middleware registered before the plugin
 | `--scim-base-map`                    | `DM_SCIM_BASE_MAP`                    | —                                                  | Path to JSON file mapping authenticated user → `{userBase, groupBase}`                           |
 | `--scim-user-object-class`           | `DM_SCIM_USER_OBJECT_CLASSES`         | `top, inetOrgPerson, organizationalPerson, person` | Object classes for created Users                                                                 |
 | `--scim-user-rdn-attribute`          | `DM_SCIM_USER_RDN_ATTRIBUTE`          | `uid`                                              | RDN attribute for Users                                                                          |
-| `--scim-user-lock-attribute`         | `DM_SCIM_USER_LOCK_ATTRIBUTE`         | `pwdAccountLockedTime`                             | LDAP attribute whose presence marks a User as `active: false`                                    |
+| `--scim-user-lock-attribute`         | `DM_SCIM_USER_LOCK_ATTRIBUTE`         | `pwdAccountLockedTime`                             | LDAP attribute whose lock value marks a User as `active: false`                                  |
 | `--scim-user-lock-value`             | `DM_SCIM_USER_LOCK_VALUE`             | —                                                  | Value written to that attribute when deactivating (required unless the attribute is the default) |
 | `--scim-group-object-class`          | `DM_SCIM_GROUP_OBJECT_CLASSES`        | `top, groupOfNames`                                | Object classes for created Groups                                                                |
 | `--scim-group-rdn-attribute`         | `DM_SCIM_GROUP_RDN_ATTRIBUTE`         | `cn`                                               | RDN attribute for Groups                                                                         |
@@ -113,23 +113,23 @@ All responses have `Content-Type: application/scim+json`.
 
 ### Default mapping (LDAP ⇄ SCIM User)
 
-| SCIM                                 | LDAP                                        |
-| ------------------------------------ | ------------------------------------------- |
-| `id`                                 | `uid` (or `entryUUID`)                      |
-| `userName`                           | `uid`                                       |
-| `externalId`                         | `employeeNumber`                            |
-| `name.familyName`                    | `sn`                                        |
-| `name.givenName`                     | `givenName`                                 |
-| `name.formatted`                     | `cn`                                        |
-| `displayName`                        | `displayName`                               |
-| `title`                              | `title`                                     |
-| `preferredLanguage`                  | `preferredLanguage`                         |
-| `emails[primary=true].value`         | `mail`                                      |
-| `emails[primary=false].value`        | `mailAlternateAddress`                      |
-| `phoneNumbers[primary=true].value`   | `telephoneNumber`                           |
-| `phoneNumbers[primary=false].value`  | `mobile`                                    |
-| `active`                             | pseudo (false if the lock attribute is set) |
-| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`       |
+| SCIM                                 | LDAP                                                      |
+| ------------------------------------ | --------------------------------------------------------- |
+| `id`                                 | `uid` (or `entryUUID`)                                    |
+| `userName`                           | `uid`                                                     |
+| `externalId`                         | `employeeNumber`                                          |
+| `name.familyName`                    | `sn`                                                      |
+| `name.givenName`                     | `givenName`                                               |
+| `name.formatted`                     | `cn`                                                      |
+| `displayName`                        | `displayName`                                             |
+| `title`                              | `title`                                                   |
+| `preferredLanguage`                  | `preferredLanguage`                                       |
+| `emails[primary=true].value`         | `mail`                                                    |
+| `emails[primary=false].value`        | `mailAlternateAddress`                                    |
+| `phoneNumbers[primary=true].value`   | `telephoneNumber`                                         |
+| `phoneNumbers[primary=false].value`  | `mobile`                                                  |
+| `active`                             | pseudo (false if the lock attribute holds the lock value) |
+| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`                     |
 
 Override with `--scim-user-mapping /path/to/user-mapping.json` (same schema as
 `static/schemas/scim/default-mapping.json`).
@@ -140,14 +140,18 @@ SCIM models account status with the boolean `active` (RFC 7643 §4.1.1), and it
 is how Okta, Entra ID and JumpCloud disable a user — they PATCH `active` to
 `false` rather than DELETE the resource.
 
-LDAP has no single equivalent, so the plugin models it on the **presence of one
-attribute**: present means locked, absent means active.
+LDAP has no single equivalent, so the plugin models it on **one attribute
+holding one value**: `--scim-user-lock-value` in `--scim-user-lock-attribute`
+means locked, anything else means active. A ppolicy lockout after failed binds
+is a timestamp in `pwdAccountLockedTime`, so it reads as active, and
+`"active": true` leaves it in place. It lasts `pwdLockoutDuration`, or until
+an administrator clears it when that is 0.
 
 | SCIM              | LDAP                                            |
 | ----------------- | ----------------------------------------------- |
 | `"active": false` | write `--scim-user-lock-value` to the attribute |
-| `"active": true`  | remove the attribute                            |
-| attribute absent  | `"active": true`                                |
+| `"active": true`  | remove the attribute if it holds the lock value |
+| lock value absent | `"active": true`                                |
 
 The default targets the ppolicy overlay:
 
@@ -184,8 +188,8 @@ neither can be told apart from a deliberate local schema:
 
 **None of this can tell whether your directory honours the value you chose.**
 The checks are on the shape of the configuration. `active` is read back from
-the mere presence of the attribute, so a value the directory stores and
-ignores still reads as `false`. Verify once, by hand, that a deactivation
+the value this plugin wrote, so a value the directory stores and ignores still
+reads as `false`. Verify once, by hand, that a deactivation
 actually prevents a bind.
 
 `active` is not a mapping entry and must not be added to a mapping file: it is
@@ -305,6 +309,17 @@ mapping contains an entry with `scim: "department"`; otherwise the server return
 `400 invalidFilter`. Same for PATCH: operations on unmapped paths produce
 `400 invalidPath`.
 
+A PATCH `add`, or a `remove` naming values, changes only the values it names:
+values the caller's read did not show, such as group members an
+`ldapsearchfilter` hides, stay. Two PATCHes changing different values of
+the same attribute both apply. Adding a value already there succeeds where
+the directory honours the permissive modify control; removing one another
+write just removed replays the PATCH on a fresh read, then answers `409`.
+A `replace`, or a `remove` of a whole attribute, sets the attribute to what
+the caller sent, and so does a group `PUT` for its members, hidden ones
+included. A group left with no member the caller saw gets the
+`--group-dummy-user` placeholder.
+
 ### Schema advertisement
 
 Schemas listed under `GET /scim/v2/Schemas` are read from
@@ -336,16 +351,16 @@ group entries works; use a mapping override if you would rather name it there.
 SCIM filters are translated to LDAP filters (RFC 4515). Values are always escaped
 via `escapeLdapFilter()` — no LDAP injection is possible.
 
-| SCIM                             | LDAP                          |
-| -------------------------------- | ----------------------------- |
-| `userName eq "alice"`            | `(uid=alice)`                 |
-| `name.familyName sw "Du"`        | `(sn=Du*)`                    |
-| `emails.value co "@example.com"` | `(mail=*@example.com*)`       |
-| `displayName pr`                 | `(displayName=*)`             |
-| `active eq true`                 | `(!(pwdAccountLockedTime=*))` |
-| `active pr`                      | `(objectClass=*)`             |
-| `a eq "x" and b eq "y"`          | `(&(a=x)(b=y))`               |
-| `not (a eq "x")`                 | `(!(a=x))`                    |
+| SCIM                             | LDAP                                      |
+| -------------------------------- | ----------------------------------------- |
+| `userName eq "alice"`            | `(uid=alice)`                             |
+| `name.familyName sw "Du"`        | `(sn=Du*)`                                |
+| `emails.value co "@example.com"` | `(mail=*@example.com*)`                   |
+| `displayName pr`                 | `(displayName=*)`                         |
+| `active eq true`                 | `(!(pwdAccountLockedTime=000001010000Z))` |
+| `active pr`                      | `(objectClass=*)`                         |
+| `a eq "x" and b eq "y"`          | `(&(a=x)(b=y))`                           |
+| `not (a eq "x")`                 | `(!(a=x))`                                |
 
 Unknown SCIM attributes raise `400 invalidFilter`.
 
@@ -605,6 +620,12 @@ Other plugins can observe and transform SCIM operations via the dynamic hooks
 `scimuserdelete`, `scimuserdeletedone`, and their `scimgroup*` equivalents, plus
 `scimbulkdone` for Bulk.
 
+`scimgroupcreate` receives the group, the request and the group base. A
+group's RDN value is its `displayName`, unless the hook sets `id` on the group
+and the group mapping stores nothing in the RDN attribute: that `id` is then
+the RDN value. An `id` sent by the client is ignored. A hook returns all
+three, so that the hooks after it still get the base.
+
 ## Exposing the configuration to client apps (`configApi`)
 
 Load `core/configApi` alongside the SCIM plugin, and `GET /api/v1/config` will

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

@@ -0,0 +1,107 @@
+# Tombstone
+
+`core/twake/tombstone` turns the delete of an account into a tombstone. The
+entry stays, so its identifiers cannot be taken by a new account, but it is
+flagged as deleted, dated, locked, carries the reason, and loses the
+attributes the deployment names.
+
+A tombstone is erased later, from an operator's decision: once the deletion
+is old enough, or right away when forced.
+
+## Behaviour
+
+- A delete of an entry whose DN matches `--twake-tombstone-dn` writes, in one
+  modify: the deleted attribute, the deletion date (now), the reason, the
+  lock, and removes `--twake-tombstone-clear-attributes`. Other entries are
+  deleted as usual.
+- A delete of an existing tombstone writes nothing and answers as a delete.
+  It fires the `twakedeletionreplay` hook with the tombstone, so
+  [lifecycle events](lifecycle-events.md) publishes the deletion again, with
+  the date of the first one. This is the way to replay a `deleted` event that
+  was lost, for instance while the broker was down.
+- The tombstone is written by the server, not as the caller: the caller's
+  delete right is what was judged, and a write right is not required on top.
+  So the `deleted` event of that write has no `$context.actor`,
+  `$context.requestId` or `$context.source`. A replay has them.
+- The tombstone keeps its group memberships until it is erased.
+- SCIM treats a tombstone as gone: reads answer 404, lists leave it out, and
+  a create with the same identity erases the tombstone and creates a new
+  entry. If the directory then refuses the new entry, the tombstone and its
+  memberships are put back once the response is sent.
+- Erasing removes the entry, then its group memberships. It publishes
+  nothing.
+- A tombstone cannot be restored. Clearing its deleted attribute by hand is
+  not a supported operation.
+
+The tombstone is written after every other plugin has judged the delete, so
+a delete that an authorization plugin refuses writes nothing.
+
+`core/ldap/trash` moves a deleted entry before this plugin sees the delete,
+so no tombstone would be written in a branch it watches. The server refuses
+to start when one of the `;`-separated `--trash-watched-bases` covers or sits under
+a `--twake-tombstone-dn` pattern, and an empty list watches every branch.
+
+## Reason
+
+The reason is, in order:
+
+- the one given to `tombstone(dn, reason, req)` by another plugin;
+- the `--twake-tombstone-reason-header` request header;
+- `--twake-tombstone-default-reason`.
+
+When `--twake-tombstone-reasons` is set, any other reason is refused with a 400. Otherwise a reason is letters, digits, `_`, `.` or `-`.
+
+## Erase
+
+```http
+POST /api/v1/twake/tombstones/erase
+Content-Type: application/json
+
+{ "dn": "uid=jdoe,ou=users,dc=example,dc=com", "force": false }
+```
+
+- `200`: erased.
+- `404`: no tombstone at this DN.
+- `409`: the deletion is younger than `--twake-tombstone-erase-min-age` and
+  `force` is not true.
+
+Other plugins call `erase(dn, { force, req })`.
+
+## Configuration
+
+The tombstone attributes are the lifecycle ones, shared with
+[lifecycle events](lifecycle-events.md):
+
+```bash
+--plugin core/twake/tombstone \
+--twake-lifecycle-lock-attribute pwdAccountLockedTime \
+--twake-lifecycle-lock-value 000001010000Z \
+--twake-lifecycle-deleted-attribute employeeType \
+--twake-lifecycle-deleted-value deleted \
+--twake-lifecycle-deleted-at-attribute roomNumber \
+--twake-lifecycle-deleted-at-format iso8601 \
+--twake-lifecycle-reason-attribute businessCategory \
+--twake-tombstone-dn '^uid=[^,]+,ou=users,dc=example,dc=com$' \
+--twake-tombstone-dn '^uid=[^,]+,ou=[^,]+,ou=organizations,dc=example,dc=com$' \
+--twake-tombstone-reasons deleted,user_request \
+--twake-tombstone-clear-attributes mobile,telephoneNumber \
+--twake-tombstone-erase-min-age 2592000 \
+--twake-tombstone-group-bases ou=groups,dc=example,dc=com
+```
+
+- `--twake-lifecycle-deleted-attribute`: required.
+- `--twake-lifecycle-lock-attribute`, `--twake-lifecycle-lock-value`: the
+  lock written on a tombstone, read as
+  [lifecycle events](lifecycle-events.md) reads it. A lock attribute other
+  than `pwdAccountLockedTime` needs its value (`TRUE` for `nsAccountLock` on
+  389-ds), or the server does not start: `000001010000Z` means nothing there.
+- `--twake-lifecycle-reason-attribute`: empty means the reason is not
+  recorded.
+- `--twake-tombstone-dn`: regular expressions, matched case-insensitively. A
+  DN holds commas, so in `DM_TWAKE_TOMBSTONE_DN` end each one with `;`.
+- `--twake-tombstone-default-reason`: default `deleted`.
+- `--twake-tombstone-reason-header`: default `x-deletion-reason`.
+- `--twake-tombstone-erase-min-age`: seconds, default 30 days.
+- `--twake-tombstone-group-bases`: where memberships are looked for at erase,
+  by `member`. Defaults to `--ldap-group-base`, then `--ldap-base`. In the
+  environment variable, end each base with `;`.

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

@@ -318,13 +318,13 @@ For each schema, the plugin generates REST API endpoints:
 ### List Entries
 
 ```bash
-GET /api/v1/ldap/{pluralName}?match={filter}&attributes={attrs}
+GET /api/v1/ldap/{pluralName}?match={value}&attribute={attrs}&attributes={attrs}&limit={n}
 ```
 
 **Example:**
 
 ```bash
-curl http://localhost:8081/api/v1/ldap/users?match=uid=*smith*&attributes=uid,cn,mail
+curl 'http://localhost:8081/api/v1/ldap/users?match=smith&attribute=uid&attributes=uid,cn,mail&limit=50'
 ```
 
 **Response:**
@@ -340,6 +340,42 @@ curl http://localhost:8081/api/v1/ldap/users?match=uid=*smith*&attributes=uid,cn
 }
 ```
 
+#### Long lists
+
+A directory lists at most a set number of entries per search for the account
+LDAP-Rest binds as (OpenLDAP: `olcSizeLimit`, default 500, or `olcLimits`;
+`size.prtotal` bounds paged searches). OpenLDAP refuses a longer list as a
+whole rather than cutting it short:
+
+- **Without `limit`**, the answer is every match or `422`:
+
+  ```json
+  {
+    "error": "Too many entries to list at once: the directory's size limit was exceeded. Narrow the search, or pass `limit`."
+  }
+  ```
+
+- **With `limit`** (a positive integer, `400` otherwise), at most `limit`
+  entries come back, with the header `X-Result-Truncated: true` when others
+  were left out. When the directory refuses the list, LDAP-Rest asks again
+  for `limit + 1` entries and answers what it gets, at most `limit` —
+  possibly fewer, if the account's own limit is lower — always with the
+  header: the directory does not say whether that answer was cut, so a
+  shorter one is not taken for complete. A request with `limit` is never
+  answered `422`.
+
+The header is absent from a complete answer. LDAP-Rest sets no CORS headers:
+a browser client on another origin sees `X-Result-Truncated` only if the
+proxy answering for it lists the header in `Access-Control-Expose-Headers`.
+
+A small `limit` costs a page of the directory's answer. A `limit` larger than
+the directory's own limit costs a walk up to that limit, then the second
+search: memory stays bounded by the directory, not by `limit`.
+
+Only the lists of the entities this plugin serves honour `limit`,
+`X-Result-Truncated` and the `422` for now. The groups list
+(`GET /api/v1/ldap/groups`) ignores `limit` and still fails with `500`.
+
 ### Get Entry
 
 ```bash

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

@@ -16,7 +16,7 @@ Plugin to intercept LDAP delete operations and move entries to a trash branch in
 ### Environment Variables
 
 - `DM_TRASH_BASE`: LDAP base DN for trash (default: `ou=trash,dc=example,dc=com`)
-- `DM_TRASH_WATCHED_BASES`: Comma-separated list of branches to watch (default: all branches except trash)
+- `DM_TRASH_WATCHED_BASES`: branches to watch, each a full DN, separated by `;` (default: all branches except trash)
 - `DM_TRASH_ADD_METADATA`: Add metadata to trashed entries (default: `true`)
 - `DM_TRASH_AUTO_CREATE`: Auto-create trash branch if missing (default: `true`)
 
@@ -25,7 +25,7 @@ Plugin to intercept LDAP delete operations and move entries to a trash branch in
 ```bash
 --plugin core/ldap/trash \
 --trash-base "ou=trash,dc=example,dc=com" \
---trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com" \
+--trash-watched-bases "ou=users,dc=example,dc=com;ou=groups,dc=example,dc=com" \
 --trash-add-metadata true \
 --trash-auto-create true
 ```
@@ -68,7 +68,7 @@ This watches all LDAP branches except the trash branch itself.
 ldap-rest \
   --plugin core/ldap/trash \
   --trash-base "ou=trash,dc=example,dc=com" \
-  --trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com"
+  --trash-watched-bases "ou=users,dc=example,dc=com;ou=groups,dc=example,dc=com"
 ```
 
 This only intercepts deletes from `ou=users` and `ou=groups`. Deletes from other branches proceed normally.
@@ -248,7 +248,7 @@ ldap-rest \
   --ldap-pwd "admin" \
   --ldap-base "dc=example,dc=com" \
   --trash-base "ou=trash,dc=example,dc=com" \
-  --trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com" \
+  --trash-watched-bases "ou=users,dc=example,dc=com;ou=groups,dc=example,dc=com" \
   --trash-add-metadata true \
   --auth-token "secret-token"
 ```