ldap-rest 0.14.0 → 0.15.0

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,8 +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
-  `displayName`, `description` or `createdAt`. Answers
+  or more; an empty one lists everything) matches the display name 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
   characters, not blank, without control characters, and unique in the

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,221 @@
+# 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",
+  "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 }`.
+
+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.
+
+A user who is deleted or becomes a tombstone publishes no member event.
+
+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"` and
+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.
+
+## 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,103 @@ 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.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.15.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": {