ldap-rest 0.14.0 → 0.16.0

package/docs/usage/configuration.md

@@ -59,18 +59,37 @@ All CLI options can be set via environment variables with the `DM_` prefix.
 
 Some options accept multiple values (e.g., `--plugin`, `--auth-token`, `--ldap-url`). These can be configured in several ways:
 
-**Via CLI - repeat the option:**
+**Via CLI - repeat the option, or give it comma-separated values:**
 
 ```bash
-ldap-rest --plugin core/auth/token --plugin core/ldap/flatGeneric --plugin core/ldap/groups
+ldap-rest --plugin core/auth/token --plugin core/ldap/flatGeneric,core/ldap/groups
 ```
 
+Only options holding identifiers split on commas: `--plugin`, `--mail-domain`,
+`--ldap-url`, the object class options (`--user-class`, `--group-class`,
+`--ldap-organization-class`, `--external-branch-class`,
+`--scim-user-object-class`, `--scim-group-object-class`,
+`--twake-space-class`), the attribute
+options (`--ldap-raw-hidden-attribute`, `--applicative-account-attribute`,
+`--ldap-operational-attribute`, `--twake-tombstone-clear-attributes`),
+`--twake-tombstone-reasons`, `--authz-for`, `--authz-dynamic-bypass` and
+`--trusted-proxy`. Any other
+option takes each value whole, so a DN or a secret keeps its commas.
+
 **Via CLI - use plural form with comma-separated values:**
 
 ```bash
 ldap-rest --plugins core/auth/token,core/ldap/flatGeneric,core/ldap/groups
 ```
 
+The plural form splits like the environment variable, see below. Give a
+DN with the repeated singular option, or separate DNs with `;` in the plural
+form:
+
+```bash
+ldap-rest --ldap-raw-base ou=users,dc=example,dc=com --ldap-raw-base ou=groups,dc=example,dc=com
+```
+
 **Via environment variable - use `;` or `,` as separator:**
 
 ```bash
@@ -81,7 +100,49 @@ export DM_PLUGINS="core/auth/token;core/ldap/flatGeneric;core/ldap/groups"
 export DM_PLUGINS="core/auth/token,core/ldap/flatGeneric,core/ldap/groups"
 ```
 
-> **Note:** If the value contains a semicolon, it will be used as the separator. Otherwise, commas are used. Whitespace around separators is ignored.
+The split depends on what the option holds. The plural form splits the same
+way:
+
+- Options holding identifiers (the list above): a value containing `;` is
+  split on `;` and spaces, any other on `,` and spaces. A value starting with
+  `;` is split on `;` too.
+- Options holding DNs or DN expressions (`--ldap-raw-base`,
+  `--james-mailing-list-branch`, `--twake-tombstone-dn`,
+  `--twake-tombstone-group-bases`, `--twake-instance-dn`): split on `;` only,
+  never on `,` nor spaces, as a DN holds both.
+  `DM_LDAP_RAW_BASE="ou=My Unit,dc=example,dc=com"` is one DN; separate
+  several DNs with `;`.
+- `--auth-hmac` (`id:secret:name`) and `--auth-totp` (`secret:name[:digits]`):
+  split on `;` if the value contains one, else on `,`, and on newlines (one
+  entry per line), never on spaces, so a name keeps its spaces. A list
+  separated by spaces is read as one entry: for HMAC the services after the
+  first cannot authenticate, and for TOTP the entry is refused. Any entry that
+  cannot work stops the server: an HMAC one with an empty id, secret or name or
+  fewer than 3 fields, a TOTP one with an empty secret or name, too many
+  fields, a secret that is not Base32 or digits that are not an integer from 6
+  to 10.
+- Any other option (tokens, paths, rules...): split on `;` if
+  the value contains one, else on `,`, and on spaces. `DM_AUTH_TOKENS="t1 t2"`
+  and `DM_AUTH_TOKENS="t1,t2"` are two tokens, and padded base64 secrets
+  (`YWJj=,ZGVm=`) split on the comma.
+
+Empty items are dropped, and each item is trimmed. A variable that is empty,
+only holds whitespace or only holds separators (`;`, `${A:-};${B:-}`), such as
+`${VAR:-}` in a compose file, counts as unset: the default applies, so an
+environment variable cannot give an empty list to an option whose default is
+not empty. The exception is `DM_LDAP_URL`, whose default `ldap://localhost` is
+a guess: an empty value stops the server. The same
+goes for an empty number or JSON value such as `DM_PORT=`. A number option
+takes an integer only: `DM_PORT=abc`, `DM_PORT=1e3`, `--port 80abc` and
+`--port --log-level debug` stop the server, and so does an empty number on the
+command line, as an empty array value does.
+The plural form of an option takes `;` before `,` too: `--auth-tokens 'a;b,c'`
+is `a` and `b,c`.
+
+Values given on the command line replace the default, and are added to those
+of the environment variable. An empty value on the command line, such as an
+unset variable expanding to nothing, stops the server: leave the option out
+to keep the default.
 
 ## General Options
 
@@ -541,6 +602,27 @@ Extends `core/ldap/groups`, whose options it reads too.
 
 See [groups](plugins/integrations/groups.md).
 
+#### `core/twake/spaces`
+
+Requires `core/twake/groups`, whose options it reads for users, groups and the
+organization entry, and `core/ldap/onChange`; with `--rabbitmq-url`, it
+requires `core/rabbitmq` and reads the organization domain from
+`--twake-instance-organization-domain-attribute`.
+
+| CLI                                    | Env                                     | Default                                | Description                                        |
+| -------------------------------------- | --------------------------------------- | -------------------------------------- | -------------------------------------------------- |
+| `--twake-space-base`                   | `DM_TWAKE_SPACE_BASE`                   |                                        | Space branch of an organization, with `{org}`      |
+| `--twake-space-class`                  | `DM_TWAKE_SPACE_CLASS`                  | `top,twakeSpace`                       | Object classes of a space                          |
+| `--twake-space-display-name-attribute` | `DM_TWAKE_SPACE_DISPLAY_NAME_ATTRIBUTE` | `twakeDisplayName`                     | Space name attribute                               |
+| `--twake-space-admin-attribute`        | `DM_TWAKE_SPACE_ADMIN_ATTRIBUTE`        | `twakeSpaceAdmin`                      | DNs holding the admin role                         |
+| `--twake-space-editor-attribute`       | `DM_TWAKE_SPACE_EDITOR_ATTRIBUTE`       | `twakeSpaceEditor`                     | DNs holding the editor role                        |
+| `--twake-space-viewer-attribute`       | `DM_TWAKE_SPACE_VIEWER_ATTRIBUTE`       | `twakeSpaceViewer`                     | DNs holding the viewer role                        |
+| `--twake-space-user-role-attribute`    | `DM_TWAKE_SPACE_USER_ROLE_ATTRIBUTE`    |                                        | User attribute holding `<space id>:<role>`, if set |
+| `--twake-space-exchange`               | `DM_TWAKE_SPACE_EXCHANGE`               | `space`                                | Topic exchange of the space events                 |
+| `--twake-space-sync-queue`             | `DM_TWAKE_SPACE_SYNC_QUEUE`             | `twake.space.sync.requested.ldap-rest` | Queue of the space sync requests                   |
+
+See [spaces](plugins/integrations/spaces.md).
+
 ### Utility Plugins
 
 #### `core/static`

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

@@ -19,6 +19,7 @@ Plugins for connecting LDAP-Rest to external systems.
 | [instances](instances.md)               | Workplace instance of each account       |
 | [tombstone](tombstone.md)               | Deleted accounts kept as tombstones      |
 | [groups](groups.md)                     | Organization groups                      |
+| [spaces](spaces.md)                     | Organization spaces, with member roles   |
 
 ## Prerequisites
 
@@ -47,4 +48,9 @@ core/twake/calendar
 core/twake/lifecycleEvents
   ├─ requires: core/ldap/onChange
   └─ requires: core/rabbitmq
+
+core/twake/spaces
+  ├─ requires: core/twake/groups
+  ├─ requires: core/ldap/onChange
+  └─ requires: core/rabbitmq (with RabbitMQ)
 ```

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

@@ -12,8 +12,14 @@ branch per organization. It serves the groups of an organization under
   display name attribute, an optional color and its creation date.
 - A group's members belong to its organization: adding a user of another
   organization, or of no organization, is refused with a 400, whichever API
-  writes the group (REST, SCIM, another plugin). The placeholder
-  (`--group-dummy-user`) is the one exception.
+  writes the group (REST, SCIM, another plugin), and so is moving a group
+  with its members, tombstones included, straight into another
+  organization's group branch: that refusal names none of them. The
+  placeholder (`--group-dummy-user`) is the one exception. Not checked:
+  moving a group out of the organizations' branches (to `ou=archive,…`, for
+  instance) or deeper than one level under another organization, which
+  takes its members along, and moving a user to another organization, whose
+  groups in the one it left keep it as a member.
 - An empty group holds the placeholder, because `groupOfNames` needs a member.
   The placeholder is never listed.
 - A tombstone (see [tombstone](tombstone.md)) keeps its memberships until it
@@ -33,7 +39,8 @@ branch per organization. It serves the groups of an organization under
 
 Every route answers 404 `ORGANIZATION_NOT_FOUND` when the organization entry
 is missing, and 410 `ORGANIZATION_DELETED` when it is deleted. Errors are
-`{ "error": "...", "code": "..." }`.
+`{ "error": "...", "code": "..." }`. A request an authorization plugin refuses
+answers 403 `REFUSED`.
 
 A group reads:
 
@@ -55,7 +62,8 @@ A group reads:
 display name reads its `cn`.
 
 - `GET /groups?page&limit&search&sortBy&sortOrder`: `search` (2 characters
-  or more) matches the display name and the description; `sortBy` is
+  or more; an empty one lists everything) matches the display name — the
+  `cn` when the group has none — and the description; `sortBy` is
   `displayName`, `description` or `createdAt`. Answers
   `{ organizationId, groups, pagination: { page, limit, total, totalPages } }`.
 - `POST /groups` with `{ name, description?, color? }`: `name` is at most 256

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

@@ -195,7 +195,9 @@ Payload and `when` values are sources:
 - 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.
+attribute. A source with no value leaves its field out. Every attribute a
+source names is requested by name when the entry is read, so an operational
+one such as `entryUUID` works anywhere in a payload or a `when`.
 
 A payload field can also list members, as an object with one key:
 

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

@@ -0,0 +1,274 @@
+# Organization Spaces
+
+`core/twake/spaces` serves the spaces of an organization under
+`/api/v1/organizations/:id/spaces`. A space gathers users and groups of the
+organization, each with a role in it: `viewer`, `editor` or `admin`.
+
+## Behaviour
+
+- A space lives in the organization's space branch, given by a DN pattern
+  where `{org}` stands for the organization id. Its `cn` is a generated UUID,
+  its name is in the display name attribute.
+- A space holds DNs in three attributes, one per role. Each holds users of
+  the organization's user branch and groups of its group branch, the
+  branches [groups](groups.md) serves.
+- A user or a group holds one role in a space. A user's role in a space is
+  the strongest of their own role and the roles of the linked groups they
+  belong to.
+- The routes keep at least one admin among a space's users: a request that
+  would demote or remove the last one is refused with 409 `LAST_ADMIN`. A
+  linked group does not count as an admin. A tombstoned or erased admin is
+  not a request, and can leave a space with none.
+- A space holds users and groups of its organization only: any other value is
+  refused with a 400, whichever API writes the space, or moves it straight
+  into another organization's space branch; a move refused names none of
+  them. Not checked: moving a space out of the organizations' branches (to
+  `ou=archive,…`, for instance) or deeper than one level under another
+  organization, which takes its holders along, and moving a user or group
+  to another organization, whose spaces in the one it left keep it. The
+  one role and the admin are kept by the routes below only; a user or group
+  a direct write, or two requests at once, left under two roles reads with
+  the strongest, and a role change or removal takes it out of all of them.
+- A tombstone (see [tombstone](tombstone.md)) keeps its roles until it is
+  erased, and is hidden from the spaces read through these routes, whatever
+  the caller may read of the user branch: it never counts as an admin. It
+  cannot be added.
+- An erased user or group leaves its spaces through the directory: enable the
+  `refint` overlay on the three role attributes.
+- When a user who is erased or becomes a tombstone was the last admin among
+  a space's users, its editors become admins, or its viewers when it has no
+  editor. A space left with no user of its own is deleted, whatever groups
+  it links. Both happen shortly after the deletion, and publish their
+  events. Erasing a tombstone checks its spaces again, for a hand-over that
+  failed or was never made. The hand-over relies on refint: without it an erased admin's DN
+  stays in the space and still counts as an admin, so erasing two admins
+  one after the other hands nothing over. A write of the space made at the
+  same moment is retried twice; past that the hand-over is logged and left
+  undone.
+- With `--twake-space-user-role-attribute`, each user entry holds one
+  `<space id>:<role>` value per space they are in, their resolved role. It
+  follows every write of a space, every change of a linked group's members,
+  and the deletion of a linked group, whichever API makes them, shortly after
+  the write. A change only tells which users to look at: each one's values
+  are then rewritten from the directory as it is, so changes made close
+  together end the same whatever order they are followed in. Values not
+  ending in `:viewer`, `:editor` or `:admin` are left alone. A tombstone keeps
+  the values it held when it was deleted.
+- With `--rabbitmq-url`, every write of a space and every change of a
+  member's role is published as an event, see below.
+- With either of the two, the plugin refuses to start when core/ldap/trash
+  watches the group or space branches: a group or space it moves away is
+  never followed.
+
+## Events
+
+Each event goes to the `--twake-space-exchange` topic exchange with the
+routing key `twake.space.<event>`. Like the user role attribute, events follow
+every write, whichever API makes it, shortly after it.
+
+```json
+{
+  "organizationId": "acme",
+  "organizationDomain": "acme.com",
+  "id": "3b9e2c71-5d4a-4f0e-9c8b-1a2d6e7f8091",
+  "members": [
+    {
+      "uuid": "6f1c0a52-8e3b-4d7f-a9c2-5b0e1d4f7a83",
+      "username": "jdoe",
+      "email": "jdoe@acme.example.org",
+      "firstName": "John",
+      "lastName": "Doe",
+      "role": "editor"
+    }
+  ],
+  "actor": "jsmith",
+  "timestamp": "2026-10-06T09:12:44.512Z"
+}
+```
+
+Every event carries `organizationId`, `id` (the space), `actor` (who made
+the write, when known) and `timestamp`. A member is described as above, its
+`uuid` the user's `entryUUID`; a group is `{ id, name, role }`.
+
+`organizationDomain` is the organization's domain, read on its entry
+(`--twake-group-organization-dn`) from
+`--twake-instance-organization-domain-attribute` (default `twakeDomain`), the
+option `twake/instances` reads too. It is kept until the entry is changed
+through this server: another replica, or a write made straight to the
+directory, keeps the old domain until restart. It is left out when
+`--twake-group-organization-dn` is empty or the entry has no such value. The
+server does not start when the directory schema does not define that
+attribute.
+
+Writes made close together blur the actor: the member events of two writes
+of one space or group followed together may go out under the first one's.
+With `--twake-space-user-role-attribute`, the follow of a write may find a
+role another write moved in another space, not followed yet: it publishes
+that event with no actor, as the later follow finds nothing left to
+announce.
+
+- `created`: `name`, `members` (every user in the space with their resolved
+  role, linked groups' members included) and `groups`.
+- `updated`: the changed `name`.
+- `deleted`.
+- `member.added`, `member.role.changed`, `member.removed`: `members`, the one
+  user whose resolved role changed, whatever the cause: a member write, a
+  group linked, unlinked or given another role, a user joining or leaving a
+  linked group. `member.removed` gives the role the user held.
+- `group.linked`, `group.role.changed`, `group.unlinked`: `groups`, the one
+  group, with its name when the event is published. A deleted group is
+  unlinked from each of its spaces once, whether refint or a later write
+  takes its DN out of them; one unlinked, then deleted before the unlink is
+  followed, is unlinked too, under its id for a name. Renaming a linked group
+  publishes nothing.
+
+- `synced`: the whole space, as `created` gives it, published by a sync.
+- `sync.completed`: `spaceIds`, the ids of every space of the organization,
+  after its `synced` events. It has no `id`.
+
+A user who is deleted or becomes a tombstone publishes no member event.
+
+## Sync
+
+An app repairs its copy of the spaces by publishing
+`twake.space.sync.requested` on the exchange:
+
+- `{ "organizationId", "id" }`: the space's `synced`, or `deleted` when it
+  is gone;
+- `{ "organizationId" }`: a `synced` for each space of the organization,
+  then `sync.completed`;
+- `{}`: a `twake.space.sync.requested` with `organizationId` for each
+  organization, the entries one level under the parent of `{org}` in
+  `--twake-space-base`, published on the exchange, so every organization is
+  synced as above.
+
+A request reaches every queue bound to its key, `twake.space.#` included.
+An app that follows the events binds `twake.space.*`, `twake.space.member.#`,
+`twake.space.group.#` and `twake.space.sync.completed`, or ignores
+`twake.space.sync.requested`.
+
+The plugin consumes these requests from the `--twake-space-sync-queue`
+quorum queue, with a dead letter queue `<queue>.dlq`. Every replica consumes
+it, several requests at once, so the events of two syncs of one organization
+may interleave: their timestamps order them. A request it cannot read goes
+to the dead letter queue. A missing organization is skipped. A deleted one
+has no space left: its `sync.completed` lists none, and a space asked is
+`deleted`. A sync whose events the broker does not take fails, and its
+request is retried, then goes to the dead letter queue.
+
+The events of a sync carry no `actor`. They all carry the time just before
+the spaces were read, so, with synchronized clocks, the event of a write
+followed after that is newer.
+An app that applies only events newer than the last one keeps the right
+state, and keeps a space created after a `sync.completed` that does not list
+it.
+
+The server does not start when the broker cannot be reached. An event the
+broker cannot take once the server runs is logged with `result: "error"`;
+the event of a write is not sent again.
+
+Member events compare each moved user's roles before and after a change:
+
+- With `--twake-space-user-role-attribute`, the roles before are the values
+  on the user's entry, so changes made close together announce each role
+  once, in whatever order they are followed.
+- Without it, the roles before are worked out from the directory with the
+  change undone. Two changes followed late may announce a role twice, or
+  not at all. Consumers that need an exact copy resync from the routes.
+
+## Routes
+
+Every route answers 404 `ORGANIZATION_NOT_FOUND` when the organization entry
+is missing, and 410 `ORGANIZATION_DELETED` when it is deleted. Errors are
+`{ "error": "...", "code": "..." }`. A request an authorization plugin refuses
+answers 403 `REFUSED`. A write answers `{ "success": true }` unless stated
+otherwise.
+
+A space reads, strongest role first:
+
+```json
+{
+  "id": "3b9e2c71-5d4a-4f0e-9c8b-1a2d6e7f8091",
+  "name": "Design Sprint",
+  "organizationId": "acme",
+  "members": [
+    { "username": "jsmith", "role": "admin" },
+    { "username": "jdoe", "role": "editor" }
+  ],
+  "groups": [{ "id": "c2a8e1f0-7b3d-4e9a-8f61-2d5b9c0e4a17", "role": "viewer" }]
+}
+```
+
+`username` is the RDN value of a user, `id` the `cn` of a group.
+
+- `GET /spaces?page&limit&search&sortBy&sortOrder&user`: `search` (2
+  characters or more) matches the name; `sortBy` is `name`. With `user`, the
+  spaces that user is in, directly or through a linked group, each with the
+  user's `role` (404 `USER_NOT_FOUND` for an unknown user). Answers
+  `{ organizationId, spaces, pagination: { page, limit, total, totalPages } }`.
+- `POST /spaces` with `{ name, members: [{ username, role }], groups?: [{ id, role }] }`:
+  `name` follows the [groups](groups.md) rule, `members` holds at least one
+  admin (400 `ADMIN_REQUIRED`), every user and group must exist in the
+  organization (404 `USER_NOT_FOUND`, `GROUP_NOT_FOUND`). Answers 201 with the
+  space.
+- `GET /spaces/:spaceId`: the space, or 404 `SPACE_NOT_FOUND`.
+- `PATCH /spaces/:spaceId` with `{ name }`: renames the space; any other
+  field is a 400.
+- `DELETE /spaces/:spaceId`.
+- `GET /spaces/:spaceId/members?page&limit&search&sortBy&sortOrder`: the
+  members' public profiles, as [groups](groups.md) answers them, each with
+  its `role`; `sortBy` is `uid` (default), `displayName`, `mail`, `jobTitle`
+  or `role`.
+- `POST /spaces/:spaceId/members` with `{ usernames: [...], role }`: every
+  user must exist in the organization (404 `USER_NOT_FOUND`, nothing added),
+  at most `--twake-group-max-page-limit` per request, as for every list of
+  users or groups below.
+  A member already holding that role is left as is; one holding another role
+  answers 409 `MEMBER_EXISTS`, nothing added.
+- `PATCH /spaces/:spaceId/members/:userId` with `{ role }`, and
+  `DELETE /spaces/:spaceId/members/:userId`: 404 `MEMBER_NOT_FOUND` for a
+  user who is not a member.
+- `GET /spaces/:spaceId/groups`: `{ organizationId, id, groups }`, each group
+  `{ id, name, role }`, by name.
+- `POST /spaces/:spaceId/groups` with `{ groupIds: [...], role }`: every group
+  must exist in the organization (404 `GROUP_NOT_FOUND`, nothing linked). A
+  group already linked with another role answers 409 `GROUP_ALREADY_LINKED`.
+- `PATCH /spaces/:spaceId/groups/:groupId` with `{ role }`, and
+  `DELETE /spaces/:spaceId/groups/:groupId`: 404 `GROUP_NOT_FOUND` for a group
+  that is not linked.
+
+## Configuration
+
+```bash
+--plugin core/twake/spaces \
+--twake-space-base 'ou=spaces,ou={org},dc=example,dc=com'
+```
+
+The plugin loads [groups](groups.md), and reads its options for the
+organization's users, groups and organization entry.
+
+- `--twake-space-base`: required, with `{org}`.
+- `--twake-space-class` (default `top,twakeSpace`): the classes of a space
+  created.
+- `--twake-space-display-name-attribute` (default `twakeDisplayName`).
+- `--twake-space-admin-attribute` (default `twakeSpaceAdmin`),
+  `--twake-space-editor-attribute` (default `twakeSpaceEditor`),
+  `--twake-space-viewer-attribute` (default `twakeSpaceViewer`): the role
+  attributes, holding DNs.
+- `--twake-space-user-role-attribute` (no default): the multi-valued user
+  attribute holding the user's role in each space, such as `twakeSpaceRole`.
+  Unset, no user entry is written.
+- `--twake-space-exchange` (default `space`): the topic exchange of the
+  events, published only when `--rabbitmq-url` is set.
+- `--twake-space-sync-queue` (default
+  `twake.space.sync.requested.ldap-rest`): the queue of the sync requests,
+  consumed only when `--rabbitmq-url` is set.
+
+## Dependencies
+
+```
+core/twake/spaces
+  ├─ requires: core/twake/groups
+  ├─ requires: core/ldap/onChange
+  └─ requires: core/rabbitmq (with RabbitMQ)
+```

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

@@ -17,7 +17,7 @@ The companion browser library is [`ldap-browser`](../../../client-development/br
 
 ### Environment Variables
 
-- `DM_LDAP_RAW_BASE`: comma-separated subtrees to expose (default: `--ldap-base`)
+- `DM_LDAP_RAW_BASE`: subtrees to expose, separated by `;` (default: `--ldap-base`)
 - `DM_LDAP_RAW_HIDDEN_ATTRIBUTES`: comma-separated attributes never returned, on top of the credential ones (default: none)
 - `DM_LDAP_RAW_SHOW_SECRETS`: serve credential attributes instead of hiding them (default: `false`)
 - `DM_LDAP_RAW_MAX_RESULTS`: maximum entries returned by a search or a children listing (default: `200`)

package/docs/usage/upgrading.md

@@ -4,6 +4,115 @@ What to check before deploying, newest first. Only releases that need a
 decision or a configuration change appear here; see the
 [CHANGELOG](../../CHANGELOG.md) for everything else.
 
+## To 0.16.0
+
+### Space events need the organization domain attribute
+
+**Who is affected:** a deployment of `core/twake/spaces` with `--rabbitmq-url`
+and `--twake-group-organization-dn`.
+
+The space events now carry the organization's domain, read from
+`--twake-instance-organization-domain-attribute` (default `twakeDomain`). The
+server does not start when the directory schema does not define that
+attribute: load a schema that does, or point the option at one it defines.
+
+## To 0.15.0
+
+### A DN option read from the environment splits on `;` only
+
+**Who is affected:** a deployment that sets `DM_LDAP_RAW_BASE`,
+`DM_JAMES_MAILING_LIST_BRANCHES`, `DM_TWAKE_TOMBSTONE_DN`,
+`DM_TWAKE_TOMBSTONE_GROUP_BASES` or `DM_TWAKE_INSTANCE_DN`, or gives
+`--ldap-raw-bases` or `--james-mailing-list-branches`.
+
+Their values are no longer cut on spaces or commas: a DN such as
+`DM_LDAP_RAW_BASE="ou=My Unit,dc=example,dc=com"` stays whole. Separate
+several DNs with `;`, as already documented.
+
+### HMAC and TOTP entries are no longer split on spaces
+
+**Who is affected:** a deployment that sets `DM_AUTH_HMAC` or `DM_AUTH_TOTP`,
+or gives `--auth-hmacs` or `--auth-totps`.
+
+Separate entries with `,`, `;` or newlines. A name may now hold spaces, as in
+`id:secret:Registration Service`. A list separated by spaces is read as one
+entry: an HMAC list gives one service, the others cannot authenticate (their
+requests get 401, and a warning is logged), and a TOTP list stops the server.
+
+`core/auth/hmac` and `core/auth/totp` also stop the server on an entry that
+cannot work, instead of skipping it with a warning: an HMAC entry with an
+empty id, secret or name or fewer than 3 fields, a TOTP entry with an empty
+secret or name, more than 3 fields, a secret that is not Base32 or digits that
+are not an integer from 6 to 10. A TOTP entry such as `secret:name:abc` used
+to register a user whose code was the string `NaN`.
+
+### The plural command-line form of an array option splits on `;` first
+
+**Who is affected:** a deployment that gives a plural form such as
+`--auth-tokens`, `--ldap-urls` or `--plugins`.
+
+A value containing `;` is now split on `;` and not on `,`, as the environment
+variable does: `--auth-tokens 'a;b;c'` was one token and is now three, and
+`--auth-tokens 'a;b,c'` was `a;b` and `c` and is now `a` and `b,c`. A value
+without `;` is split as before.
+
+`--authz-dynamic-bypass` and `--twake-space-class` now split on commas in their
+singular form, as the other options holding identifiers do.
+
+### An empty environment variable or a number that is not one
+
+**Who is affected:** a deployment that sets an array option, a number or a JSON
+option to an empty value, or a number option to something else than an integer.
+
+- An array variable that is empty, only holds whitespace or only holds
+  separators (`DM_GROUP_CLASSES=`, `DM_GROUP_CLASSES=,`) keeps the default
+  instead of giving an empty list, which was a silent misconfiguration (a
+  server without object class, for instance). `DM_LDAP_OPERATIONAL_ATTRIBUTES=`
+  used to give `[]` and now gives the default; an option with a non-empty
+  default cannot be given an empty list from the environment.
+- `DM_LDAP_URL=` is the exception: its default, `ldap://localhost`, is a guess,
+  not a fallback, so an empty value still stops the server. Set the variable
+  or leave it out.
+- An empty number or JSON value (`DM_PORT=`) keeps its default instead of
+  giving `NaN` or stopping the server.
+- A number option takes an integer only: `DM_PORT=abc`, `DM_PORT=1e3`,
+  `DM_PORT=8080abc`, `--port ''` or `--port --log-level debug` stop the server
+  instead of giving `NaN` or a truncated value.
+
+Booleans and strings are unchanged.
+
+### An array option on the command line replaces its default
+
+**Who is affected:** a deployment that gives, on the command line, an array
+option that has a default: `--user-class`, `--group-class`,
+`--ldap-organization-class`, `--external-branch-class`,
+`--scim-user-object-class`, `--scim-group-object-class`,
+`--applicative-account-attribute`, `--ldap-operational-attribute` or
+`--ldap-url`, in their singular or plural form.
+
+Their values used to be added to the default, and now replace it. Repeat the
+default values you want to keep:
+
+```bash
+# Until now: top, twakeAccount, twakeWhitePages, twakeExtra
+ldap-rest --user-class twakeExtra
+
+# Now
+ldap-rest --user-class top,twakeAccount,twakeWhitePages,twakeExtra
+```
+
+Without its default classes, an entry is created without its structural
+class. Without the default operational attributes, `appAccountsConsistency`
+recreates an applicative account with `userPassword` and the attributes the
+directory generates. The defaults are listed in
+[the configuration reference](configuration.md).
+
+`--ldap-url ldap://ldap.example.com` no longer keeps `ldap://localhost` next
+to it.
+
+An environment variable already replaced the default, and values given on the
+command line are still added to it.
+
 ## To 0.14.0
 
 ### `--twake-instance-organization-account` is removed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -288,6 +288,10 @@
       "types": "./dist/src/plugins/twake/lifecycleEvents.d.ts",
       "import": "./dist/plugins/twake/lifecycleEvents.js"
     },
+    "./plugin-twake-spaces": {
+      "types": "./dist/src/plugins/twake/spaces.d.ts",
+      "import": "./dist/plugins/twake/spaces.js"
+    },
     "./plugin-twake-tombstone": {
       "types": "./dist/src/plugins/twake/tombstone.d.ts",
       "import": "./dist/plugins/twake/tombstone.js"
@@ -733,6 +737,7 @@
     "fast-xml-parser": ">=5.3.6",
     "glob": ">=11.0.4",
     "minimatch": "^10.2.1",
+    "postcss-selector-parser": "^7.1.6",
     "serialize-javascript": ">=7.0.3"
   },
   "dependencies": {
@@ -770,7 +775,6 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^5.5.4",
-    "fast-glob": "^3.3.3",
     "globals": "^14.0.0",
     "js-yaml": "^4.1.1",
     "mocha": "^12.0.0",
@@ -781,6 +785,7 @@
     "rollup-plugin-postcss": "^4.0.2",
     "sort-package-json": "^3.4.0",
     "supertest": "^7.1.4",
+    "tinyglobby": "^0.2.17",
     "tslib": "^2.8.1",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2"