ldap-rest 0.11.2 → 0.13.0

package/docs/usage/configuration.md

@@ -191,7 +191,7 @@ at `0` otherwise.
 | CLI                     | Env                      | Default | Description                 |
 | ----------------------- | ------------------------ | ------- | --------------------------- |
 | `--trash-base`          | `DM_TRASH_BASE`          |         | Trash container DN          |
-| `--trash-watched-bases` | `DM_TRASH_WATCHED_BASES` |         | DNs to watch for deletions  |
+| `--trash-watched-bases` | `DM_TRASH_WATCHED_BASES` |         | `;`-separated DNs to watch  |
 | `--trash-add-metadata`  | `DM_TRASH_ADD_METADATA`  | `true`  | Add deletion metadata       |
 | `--trash-auto-create`   | `DM_TRASH_AUTO_CREATE`   | `true`  | Auto-create trash container |
 
@@ -445,6 +445,102 @@ Automatically creates/updates/deletes applicative account entries when users are
 
 **Requires:** `core/ldap/onChange`
 
+#### `core/twake/lifecycleEvents`
+
+| CLI                                      | Env                                       | Default                      | Description                                                                                                      |
+| ---------------------------------------- | ----------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--twake-lifecycle-role-attribute`       | `DM_TWAKE_LIFECYCLE_ROLE_ATTRIBUTE`       |                              | Role attribute                                                                                                   |
+| `--twake-lifecycle-lock-attribute`       | `DM_TWAKE_LIFECYCLE_LOCK_ATTRIBUTE`       | `--scim-user-lock-attribute` | Lock attribute                                                                                                   |
+| `--twake-lifecycle-lock-value`           | `DM_TWAKE_LIFECYCLE_LOCK_VALUE`           | see description              | Value marking an account locked: SCIM's with SCIM's attribute, required with another than `pwdAccountLockedTime` |
+| `--twake-lifecycle-deleted-attribute`    | `DM_TWAKE_LIFECYCLE_DELETED_ATTRIBUTE`    |                              | Attribute marking a tombstone                                                                                    |
+| `--twake-lifecycle-deleted-value`        | `DM_TWAKE_LIFECYCLE_DELETED_VALUE`        | `TRUE`                       | Value marking a tombstone                                                                                        |
+| `--twake-lifecycle-deleted-at-attribute` | `DM_TWAKE_LIFECYCLE_DELETED_AT_ATTRIBUTE` |                              | Deletion date attribute                                                                                          |
+| `--twake-lifecycle-deleted-at-format`    | `DM_TWAKE_LIFECYCLE_DELETED_AT_FORMAT`    | `iso8601`                    | `iso8601` or `generalizedTime`                                                                                   |
+| `--twake-lifecycle-rules`                | `DM_TWAKE_LIFECYCLE_RULES`                |                              | Rules: a JSON file, or the JSON itself                                                                           |
+| `--twake-lifecycle-member-attribute`     | `DM_TWAKE_LIFECYCLE_MEMBER_ATTRIBUTE`     | `member`                     | Attribute holding a group's members                                                                              |
+
+See [lifecycle events](plugins/integrations/lifecycle-events.md).
+
+**Requires:** `core/ldap/onChange`, `core/rabbitmq`
+
+#### `core/twake/instances`
+
+| CLI                                              | Env                                               | Default                               | Description                                               |
+| ------------------------------------------------ | ------------------------------------------------- | ------------------------------------- | --------------------------------------------------------- |
+| `--twake-instance-dn`                            | `DM_TWAKE_INSTANCE_DN`                            | `[]`                                  | DN expressions of the accounts to equip                   |
+| `--twake-instance-skip-attribute`                | `DM_TWAKE_INSTANCE_SKIP_ATTRIBUTE`                |                                       | Attribute marking an account with no instance             |
+| `--twake-instance-skip-value`                    | `DM_TWAKE_INSTANCE_SKIP_VALUE`                    |                                       | Its value                                                 |
+| `--twake-instance-provider`                      | `DM_TWAKE_INSTANCE_PROVIDER`                      | `cloudery`                            | `cloudery` or `cozy-stack`                                |
+| `--twake-instance-id`                            | `DM_TWAKE_INSTANCE_ID`                            | `{uid}`                               | Instance id template                                      |
+| `--twake-instance-fqdn-attribute`                | `DM_TWAKE_INSTANCE_FQDN_ATTRIBUTE`                | `twakeWorkspaceUrl`                   | Address attribute                                         |
+| `--twake-instance-sent-attribute`                | `DM_TWAKE_INSTANCE_SENT_ATTRIBUTE`                | `twakeCreatedEventAt`                 | Date the creation event was sent                          |
+| `--twake-instance-locale`                        | `DM_TWAKE_INSTANCE_LOCALE`                        | `en`, `fr` with cozy-stack            | Locale when the entry has none                            |
+| `--twake-instance-timeout`                       | `DM_TWAKE_INSTANCE_TIMEOUT`                       | `30000`                               | Milliseconds a provider call may take                     |
+| `--twake-instance-cloudery-url`                  | `DM_TWAKE_INSTANCE_CLOUDERY_URL`                  |                                       | Cloudery API                                              |
+| `--twake-instance-cloudery-token`                | `DM_TWAKE_INSTANCE_CLOUDERY_TOKEN`                |                                       | Its token                                                 |
+| `--twake-instance-cloudery-domain`               | `DM_TWAKE_INSTANCE_CLOUDERY_DOMAIN`               |                                       | Domain of the instances                                   |
+| `--twake-instance-cloudery-offer`                | `DM_TWAKE_INSTANCE_CLOUDERY_OFFER`                | `b2b_twake_default`                   | Offer of an account's instance                            |
+| `--twake-instance-cloudery-organization-offer`   | `DM_TWAKE_INSTANCE_CLOUDERY_ORGANIZATION_OFFER`   |                                       | Offer of an organization's instance                       |
+| `--twake-instance-cozy-url`                      | `DM_TWAKE_INSTANCE_COZY_URL`                      |                                       | cozy-stack admin API                                      |
+| `--twake-instance-cozy-user`                     | `DM_TWAKE_INSTANCE_COZY_USER`                     | `admin`                               | Its user                                                  |
+| `--twake-instance-cozy-passphrase`               | `DM_TWAKE_INSTANCE_COZY_PASSPHRASE`               |                                       | Its passphrase                                            |
+| `--twake-instance-cozy-domain`                   | `DM_TWAKE_INSTANCE_COZY_DOMAIN`                   |                                       | Domain of the instances                                   |
+| `--twake-instance-cozy-context`                  | `DM_TWAKE_INSTANCE_COZY_CONTEXT`                  | `default`                             | cozy-stack context                                        |
+| `--twake-instance-cozy-apps`                     | `DM_TWAKE_INSTANCE_COZY_APPS`                     | `home,drive,settings,notes,dataproxy` | Apps installed on a new instance                          |
+| `--twake-instance-cozy-org-id`                   | `DM_TWAKE_INSTANCE_COZY_ORG_ID`                   |                                       | Organization id when the DN gives none                    |
+| `--twake-instance-cozy-org-domain`               | `DM_TWAKE_INSTANCE_COZY_ORG_DOMAIN`               |                                       | Organization domain when the DN gives none                |
+| `--twake-instance-auth-exchange`                 | `DM_TWAKE_INSTANCE_AUTH_EXCHANGE`                 | `auth`                                | Exchange of account events                                |
+| `--twake-instance-b2b-exchange`                  | `DM_TWAKE_INSTANCE_B2B_EXCHANGE`                  | `b2b`                                 | Exchange of organization events                           |
+| `--twake-instance-user-created-key`              | `DM_TWAKE_INSTANCE_USER_CREATED_KEY`              | `user.created`                        | Routing key of an account's creation                      |
+| `--twake-instance-organization-created-key`      | `DM_TWAKE_INSTANCE_ORGANIZATION_CREATED_KEY`      | `organization.created`                | Routing key of an organization's creation                 |
+| `--twake-instance-workplace-created-key`         | `DM_TWAKE_INSTANCE_WORKPLACE_CREATED_KEY`         | `workplace.created`                   | Routing key the Cloudery announces on                     |
+| `--twake-instance-queue`                         | `DM_TWAKE_INSTANCE_QUEUE`                         | `workplace.created.ldap-rest`         | Queue shared by the replicas                              |
+| `--twake-instance-organization-base`             | `DM_TWAKE_INSTANCE_ORGANIZATION_BASE`             |                                       | Branch of the organization entries                        |
+| `--twake-instance-organization-id-attribute`     | `DM_TWAKE_INSTANCE_ORGANIZATION_ID_ATTRIBUTE`     | `ou`                                  | Attribute holding an organization's id                    |
+| `--twake-instance-organization-domain-attribute` | `DM_TWAKE_INSTANCE_ORGANIZATION_DOMAIN_ATTRIBUTE` | `twakeDomain`                         | Attribute holding an organization's domain                |
+| `--twake-instance-organization-name-attribute`   | `DM_TWAKE_INSTANCE_ORGANIZATION_NAME_ATTRIBUTE`   | `description`                         | Attribute holding an organization's name                  |
+| `--twake-instance-organization-fqdn-attribute`   | `DM_TWAKE_INSTANCE_ORGANIZATION_FQDN_ATTRIBUTE`   |                                       | Address attribute of an organization (empty: not written) |
+
+See [instances](plugins/integrations/instances.md).
+
+**Requires:** `core/rabbitmq`
+
+#### `core/twake/tombstone`
+
+Reads the `--twake-lifecycle-*` attributes above, and:
+
+| CLI                                  | Env                                   | Default             | Description                               |
+| ------------------------------------ | ------------------------------------- | ------------------- | ----------------------------------------- |
+| `--twake-lifecycle-reason-attribute` | `DM_TWAKE_LIFECYCLE_REASON_ATTRIBUTE` |                     | Deletion reason attribute                 |
+| `--twake-tombstone-dn`               | `DM_TWAKE_TOMBSTONE_DN`               | `[]`                | DN patterns of entries kept as tombstones |
+| `--twake-tombstone-default-reason`   | `DM_TWAKE_TOMBSTONE_DEFAULT_REASON`   | `deleted`           | Reason when none is given                 |
+| `--twake-tombstone-reason-header`    | `DM_TWAKE_TOMBSTONE_REASON_HEADER`    | `x-deletion-reason` | Request header carrying the reason        |
+| `--twake-tombstone-reasons`          | `DM_TWAKE_TOMBSTONE_REASONS`          | `[]`                | Accepted reasons (empty: any)             |
+| `--twake-tombstone-clear-attributes` | `DM_TWAKE_TOMBSTONE_CLEAR_ATTRIBUTES` | `[]`                | Attributes removed from a tombstone       |
+| `--twake-tombstone-erase-min-age`    | `DM_TWAKE_TOMBSTONE_ERASE_MIN_AGE`    | `2592000`           | Seconds before a tombstone may be erased  |
+| `--twake-tombstone-group-bases`      | `DM_TWAKE_TOMBSTONE_GROUP_BASES`      | `--ldap-group-base` | Where memberships are removed at erase    |
+
+See [tombstone](plugins/integrations/tombstone.md).
+
+#### `core/twake/groups`
+
+Extends `core/ldap/groups`, whose options it reads too.
+
+| CLI                                           | Env                                            | Default            | Description                                           |
+| --------------------------------------------- | ---------------------------------------------- | ------------------ | ----------------------------------------------------- |
+| `--twake-group-base`                          | `DM_TWAKE_GROUP_BASE`                          |                    | Group branch of an organization, with `{org}`         |
+| `--twake-group-user-base`                     | `DM_TWAKE_GROUP_USER_BASE`                     |                    | User branch of an organization, with `{org}`          |
+| `--twake-group-organization-dn`               | `DM_TWAKE_GROUP_ORGANIZATION_DN`               |                    | Organization entry, with `{org}` (empty: not checked) |
+| `--twake-group-organization-status-attribute` | `DM_TWAKE_GROUP_ORGANIZATION_STATUS_ATTRIBUTE` | `twakeOrgStatus`   | Organization status attribute                         |
+| `--twake-group-organization-deleted-value`    | `DM_TWAKE_GROUP_ORGANIZATION_DELETED_VALUE`    | `deleted`          | Status of a deleted organization                      |
+| `--twake-group-display-name-attribute`        | `DM_TWAKE_GROUP_DISPLAY_NAME_ATTRIBUTE`        | `twakeDisplayName` | Group display name attribute                          |
+| `--twake-group-color-attribute`               | `DM_TWAKE_GROUP_COLOR_ATTRIBUTE`               | `twakeGroupColor`  | Group color attribute                                 |
+| `--twake-group-created-at-attribute`          | `DM_TWAKE_GROUP_CREATED_AT_ATTRIBUTE`          | `twakeCreatedAt`   | Group creation date attribute                         |
+| `--twake-group-max-page-limit`                | `DM_TWAKE_GROUP_MAX_PAGE_LIMIT`                | `1000`             | Largest page, and most users added at once            |
+| `--twake-group-member-fields`                 | `DM_TWAKE_GROUP_MEMBER_FIELDS`                 | `{}`               | Member profile fields over the defaults, as JSON      |
+
+See [groups](plugins/integrations/groups.md).
+
 ### Utility Plugins
 
 #### `core/static`

package/docs/usage/plugins/README.md

@@ -53,12 +53,16 @@ Protection and rate limiting:
 
 Connect to external systems:
 
-| Plugin                                             | Description                        |
-| -------------------------------------------------- | ---------------------------------- |
-| [james-mail](integrations/james-mail.md)           | Apache James synchronization       |
-| [james-mailboxes](integrations/james-mailboxes.md) | Apache James team mailboxes        |
-| [calendar](integrations/calendar.md)               | Twake Calendar resources and users |
-| [app-accounts](integrations/app-accounts.md)       | Applicative accounts API           |
+| Plugin                                               | Description                          |
+| ---------------------------------------------------- | ------------------------------------ |
+| [james-mail](integrations/james-mail.md)             | Apache James synchronization         |
+| [james-mailboxes](integrations/james-mailboxes.md)   | Apache James team mailboxes          |
+| [calendar](integrations/calendar.md)                 | Twake Calendar resources and users   |
+| [app-accounts](integrations/app-accounts.md)         | Applicative accounts API             |
+| [lifecycle-events](integrations/lifecycle-events.md) | Account lifecycle events to RabbitMQ |
+| [instances](integrations/instances.md)               | Workplace instance of each account   |
+| [tombstone](integrations/tombstone.md)               | Deleted accounts kept as tombstones  |
+| [groups](integrations/groups.md)                     | Organization groups                  |
 
 ## Utility Plugins
 

package/docs/usage/plugins/auth/oidc.md

@@ -85,6 +85,52 @@ client (`Accept: application/json`) receives 401. Every other authentication
 plugin in this repository answers JSON 401 throughout — the difference is
 kept because it is what makes a login work at all.
 
+## Session lifetime
+
+A session lasts no longer than its access token. Once the token has expired,
+the next request renews it with the refresh token, when the provider gave
+one; without a refresh token, or when the provider refuses the renewal, the
+session ends and the request is answered as an unauthenticated one: the
+browser goes back through the provider, which signs the caller in again
+without asking anything while its own session lasts.
+
+So that renewals do not cost a round trip through the provider, have it
+issue refresh tokens to this client (LemonLDAP::NG: _Issue refresh tokens_
+in the relying party's options). A token the provider gives no expiry keeps
+the session for the cookie's own lifetime.
+
+Nothing serialises the renewals: requests arriving together with the same
+expired cookie each send the refresh token. A provider that rotates refresh
+tokens refuses all but one, and the requests it refused end their session:
+the caller signs in again, silently while the provider's session lasts.
+
+## Logout
+
+`/logout` ends the session at the provider as well (RP-Initiated Logout): the
+browser is sent to the provider's `end_session_endpoint` with the id token as
+`id_token_hint`, and the provider closes its own session — and, with
+[Back-Channel Logout](back-channel-logout.md), tells the other applications.
+No `post_logout_redirect_uri` is sent: the caller ends on the provider's own
+logout page, and nothing has to be registered there.
+
+Ending the cookie alone would not log anyone out: every guarded path goes
+through the provider, which still holds its session and logs the caller back
+in without asking anything.
+
+A provider whose discovery document names no `end_session_endpoint` gets a
+local logout — the cookie is dropped, the browser goes to `--base-url` — and
+a warning saying the provider may log the caller back in.
+
+`GET /v1/config` (with `core/configApi`) publishes the route, so a front-end
+knows it can offer a sign-out control. The key is `openidconnect` whatever
+the instance is named:
+
+```json
+"features": {
+  "openidconnect": { "enabled": true, "endpoints": { "logout": "/logout" } }
+}
+```
+
 ## How It Works
 
 1. Uses `express-openid-connect` for OAuth2/OIDC flow

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

@@ -11,10 +11,14 @@ Plugins for connecting LDAP-Rest to external systems.
 
 ## Twake
 
-| Plugin                          | Description                              |
-| ------------------------------- | ---------------------------------------- |
-| [calendar](calendar.md)         | Calendar resources and users sync        |
-| [app-accounts](app-accounts.md) | Applicative accounts API (devices, apps) |
+| Plugin                                  | Description                              |
+| --------------------------------------- | ---------------------------------------- |
+| [calendar](calendar.md)                 | Calendar resources and users sync        |
+| [app-accounts](app-accounts.md)         | Applicative accounts API (devices, apps) |
+| [lifecycle-events](lifecycle-events.md) | Account lifecycle events to RabbitMQ     |
+| [instances](instances.md)               | Workplace instance of each account       |
+| [tombstone](tombstone.md)               | Deleted accounts kept as tombstones      |
+| [groups](groups.md)                     | Organization groups                      |
 
 ## Prerequisites
 
@@ -39,4 +43,8 @@ core/twake/james
 
 core/twake/calendar
   └─ requires: core/ldap/onChange
+
+core/twake/lifecycleEvents
+  ├─ requires: core/ldap/onChange
+  └─ requires: core/rabbitmq
 ```

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

@@ -0,0 +1,225 @@
+# Organization Groups
+
+`core/twake/groups` is [`core/ldap/groups`](../ldap/groups.md) with one group
+branch per organization. It serves the groups of an organization under
+`/api/v1/organizations/:id/groups`, in place of the flat `/api/v1/ldap/groups`.
+
+## Behaviour
+
+- An organization's groups and users live in branches given by DN patterns,
+  where `{org}` stands for the organization id.
+- A group is a `groupOfNames` with a generated `cn` (a UUID), its name in the
+  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.
+- 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
+  is erased, and is hidden from every member list read through LDAP-Rest.
+  A SCIM `PUT` of a group replaces its whole member list, so it drops the
+  hidden tombstones too; the routes below add and remove one member at a
+  time and keep them. Hiding them costs one search of each organization's
+  user branch per search that returns a group with its members, whichever
+  plugin makes it.
+- An erased member leaves its groups through the directory: enable the
+  `refint` overlay on `member`. Unlike `core/ldap/groups`, this plugin does
+  not remove a deleted entry from its groups itself, since that write would
+  announce a member removed on an erase.
+- Every route of an organization whose status says deleted answers 410.
+
+## 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 group reads:
+
+```json
+{
+  "id": "8f14e45f-ceea-467d-9a3e-7c2b0a1d5e10",
+  "cn": "8f14e45f-ceea-467d-9a3e-7c2b0a1d5e10",
+  "displayName": "Engineering",
+  "description": "Engineering team",
+  "color": "#3366FF",
+  "organizationId": "acme",
+  "baseDN": "cn=8f14e45f-ceea-467d-9a3e-7c2b0a1d5e10,ou=groups,ou=acme,dc=example,dc=com",
+  "members": ["jdoe"],
+  "createdAt": "2026-01-23T11:00:00.000Z"
+}
+```
+
+`members` are the RDN values of the organization's users. A group without a
+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
+  `{ 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
+  organization among groups made here (409 `GROUP_EXISTS`); `color` is `#RGB`
+  or `#RRGGBB`. Answers 201 with the group.
+- `GET /groups/:groupId`: the group, or 404 `GROUP_NOT_FOUND`.
+- `PATCH /groups/:groupId` with any of `name`, `description`, `color`: an
+  empty `description` or `color` clears it; any other field is a 400.
+- `DELETE /groups/:groupId`.
+- `GET /groups/:groupId/members?page&limit&search&sortBy&sortOrder`: the
+  members' public profiles, `sortBy` `uid` (default), `displayName`, `mail`
+  or `jobTitle`. A member that cannot be read is `{ "uid": "..." }`.
+- `POST /groups/:groupId/members` with `{ usernames: [...] }`: every user must
+  exist in the organization (404 `USER_NOT_FOUND`, nothing added), at most
+  `--twake-group-max-page-limit` per request.
+- `DELETE /groups/:groupId/members/:userId`: 404 `MEMBER_NOT_FOUND` for a user
+  who is not a member.
+
+Name uniqueness holds for groups made through these routes only: an identity
+provider may push two groups of one name, and a SCIM create is never refused
+for it.
+
+## Configuration
+
+```bash
+--plugin core/twake/groups \
+--twake-group-base 'ou=groups,ou={org},dc=example,dc=com' \
+--twake-group-user-base 'ou=users,ou={org},dc=example,dc=com' \
+--twake-group-organization-dn 'ou={org},dc=example,dc=com' \
+--group-class top,groupOfNames,twakeGroup \
+--group-dummy-user cn=placeholder \
+--group-schema static/schemas/twake/organizationGroups.json
+```
+
+- `--group-schema`: `static/schemas/twake/organizationGroups.json` declares
+  the groups' `cn`, members and description. The default group schema
+  describes department groups and requires `twakeDepartmentLink`, which these
+  groups do not have. Groups created through SCIM are written directly and
+  are not checked against this schema.
+- `--twake-group-base`, `--twake-group-user-base`: required, each with
+  `{org}`.
+- `--twake-group-organization-dn`: the organization entry. Empty means no
+  organization is checked.
+- `--twake-group-organization-status-attribute` (default `twakeOrgStatus`),
+  `--twake-group-organization-deleted-value` (default `deleted`).
+- `--twake-group-display-name-attribute` (default `twakeDisplayName`),
+  `--twake-group-color-attribute` (default `twakeGroupColor`),
+  `--twake-group-created-at-attribute` (default `twakeCreatedAt`): the
+  group's attributes. The group classes (`--group-class`) must allow them.
+  The plugin adds them to the loaded group schema under these names, in any
+  case, so a renamed attribute needs no schema of its own.
+- `--twake-group-max-page-limit` (default 1000): the largest page, and the
+  most users added in one request.
+- `--twake-group-member-fields`: JSON of `{ field: attribute }` for the member
+  profile, over the defaults `uid`, `_id` (`entryUUID`), `cn`, `sn`,
+  `givenName`, `displayName`, `mail`, `mobile`, `jobTitle`
+  (`twakeJobTitle`), `company` (`twakeCompany`), `organizationRole`
+  (`twakeOrganizationRole`) and `organizationId` (`twakeOrganizationId`).
+  A profile also has `name` from `sn`, `givenName`, `twakeAdditionalName` and
+  `twakeNamePrefix`, and `isTechnical` from `twakeIsTechnical`.
+- Tombstones are recognized by `--twake-lifecycle-deleted-attribute` and
+  `--twake-lifecycle-deleted-value`, as [tombstone](tombstone.md) writes them.
+
+## Events
+
+[Lifecycle events](lifecycle-events.md) publishes a group's changes from the
+directory writes, whichever API made them. A rule for the pattern above:
+
+```json
+{
+  "dn": "^cn=(?<id>[^,]+),ou=groups,ou=(?<org>[^,]+),dc=example,dc=com$",
+  "exchange": "groups",
+  "events": {
+    "created": {
+      "routingKey": "group.created",
+      "payload": {
+        "organizationId": "$dn.org",
+        "id": "$dn.id",
+        "name": "$twakeDisplayName",
+        "description": "$description",
+        "color": "$twakeGroupColor",
+        "createdAt": "$twakeCreatedAt",
+        "members": { "$members": { "username": "$uid", "email": "$mail" } },
+        "timestamp": "$now"
+      }
+    },
+    "updated": {
+      "routingKey": "group.updated",
+      "payload": {
+        "organizationId": "$dn.org",
+        "id": "$dn.id",
+        "name": "$changed.twakeDisplayName",
+        "description": "$changed.description",
+        "color": "$changed.twakeGroupColor",
+        "timestamp": "$now"
+      }
+    },
+    "memberAdded": {
+      "routingKey": "group.member.added",
+      "payload": {
+        "organizationId": "$dn.org",
+        "id": "$dn.id",
+        "members": {
+          "$added": {
+            "username": "$uid",
+            "email": "$mail",
+            "firstName": "$givenName",
+            "lastName": "$sn"
+          }
+        },
+        "timestamp": "$now"
+      }
+    },
+    "memberRemoved": {
+      "routingKey": "group.member.removed",
+      "payload": {
+        "organizationId": "$dn.org",
+        "id": "$dn.id",
+        "members": { "$removed": { "username": "$uid", "email": "$mail" } },
+        "timestamp": "$now"
+      }
+    },
+    "deleted": {
+      "routingKey": "group.deleted",
+      "payload": {
+        "organizationId": "$dn.org",
+        "id": "$dn.id",
+        "timestamp": "$now"
+      }
+    }
+  }
+}
+```
+
+Erasing a member publishes no `memberRemoved` when the directory's `refint`
+removes it from its groups, since that write does not go through LDAP-Rest.
+Without `refint`, the [tombstone](tombstone.md) erase takes the member out
+of the groups under `--twake-tombstone-group-bases` itself, through
+LDAP-Rest: each of those groups then publishes a `memberRemoved` naming the
+member by its RDN. That option defaults to the flat group base, which holds
+no group here; point it at the organizations' group branches.
+
+## SCIM groups
+
+SCIM groups take the organization's group branch through SCIM's per-request
+group base (`--scim-group-base-header`, `--scim-base-header-root`), the same
+classes through `--scim-group-object-class`, and the provider's `externalId`
+through `--scim-group-external-id-attribute`. Map SCIM `displayName` to the
+display name attribute in `--scim-group-mapping`: the name is kept there,
+SCIM reads, updates and `displayName` filters go through it, and a SCIM group
+of an organization gets a generated `cn` (a UUID), which is also its SCIM
+`id`, and a creation date, as a group made by the routes does. The date is
+added only to a group that holds the display name attribute, so classes that
+allow the display name must allow the creation date too: the default
+attributes both come with `twakeGroup`, but a display name kept in an
+attribute `groupOfNames` allows, such as `description`, next to the default
+`twakeCreatedAt` makes every SCIM create fail. Without that mapping, a SCIM
+group's `cn` is its `displayName`, and the plugin logs a warning at startup. A group whose `cn` is already its `displayName` keeps
+that `cn` and `id`.
+
+## Dependencies
+
+```
+core/twake/groups
+  └─ extends: core/ldap/groups
+```

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

@@ -0,0 +1,150 @@
+# Workplace Instances
+
+`core/twake/instances` gives every account this server creates its workplace
+instance. It replaces `core/twake/cozyProvision` and
+`core/twake/clouderyProvision`, and refuses to start when either is loaded
+too. What changes when moving to it is in the
+[upgrade notes](../../upgrading.md#twakeinstances-replaces-cozyprovision-and-clouderyprovision).
+
+Every account must be created through this server (REST, SCIM, the LSC
+plugin, scripts through the API). An entry written straight to the directory
+gets no instance.
+
+## Behaviour
+
+- Once an add has written an entry whose DN matches `--twake-instance-dn`,
+  the instance is looked up, then asked for if missing, before the add
+  answers (through the
+  [`ldapaddafter`](../../../plugin-development/hooks.md#ldapaddafter) hook).
+  An entry holding `--twake-instance-skip-value` in
+  `--twake-instance-skip-attribute`, a technical account for instance, gets
+  none, and neither does a tombstone
+  (`--twake-lifecycle-deleted-attribute`) put back in place.
+- The address (`--twake-instance-fqdn-attribute`) and the mark
+  (`--twake-instance-sent-attribute`) are this plugin's to write: an add that
+  carries them has them removed, and an address written by a modify is taken
+  only when it is the one the provider gives the account, or once the
+  provider confirms it.
+- A refused, unreachable or slow provider leaves the entry written and
+  without an address: it is pending, and the error is logged. The add itself
+  succeeds, whatever the door (REST, SCIM, bulk import).
+  `--twake-instance-timeout` bounds each call, so a lookup, a creation and,
+  with cozy-stack, the onboarding can hold an add up to three times as long.
+- Once the instance exists, its address is written, `user.created` is
+  published on the auth exchange, without a password hash, and the entry is
+  marked with the date. The event is sent at least once: a failure between
+  the publication and the mark sends it again on the next attempt, and two
+  replicas handling the same account at once may both send it. Within one
+  replica, the work on one account is done one step at a time.
+- The server does not start without a reachable broker, and an event that
+  cannot be published fails its attempt rather than being marked as sent.
+- With cozy-stack, deleting an account destroys its instance, when that
+  instance's OIDC id is this account's.
+
+## Making sure an account has its instance
+
+`POST /api/v1/twake/instances/ensure` with `{ "dn": … }` or `{ "mail": … }`
+(or `ensureInstance(dn)` from another plugin) writes a missing address and
+announces the account when its instance exists, and asks for the instance
+when it does not. It answers `ready` or `pending`, and `400` when the body
+names no account.
+
+The route reads and writes the account with the caller's rights: an account
+the caller cannot read answers `404`, as a missing one does, and one it
+cannot write is refused before the provider or the broker hear of it.
+
+Pending accounts are the entries under the `--twake-instance-dn` branches
+with a mail and no address, for instance
+`(&(mail=*)(!(twakeWorkspaceUrl=*)))`, technical accounts aside.
+
+## Organizations
+
+`ensureOrganization({ id, name, domain })` asks for an organization's own
+instance, for the application that creates organizations to call once it
+has written the organization entry. With the Cloudery it creates the
+Cloudery organization first. The organization entry, found under
+`--twake-instance-organization-base` by
+`--twake-instance-organization-id-attribute`, gets the address when
+`--twake-instance-organization-fqdn-attribute` names where. With the
+Cloudery the organization is then linked to its instance (`PATCH
+/api/v2/organizations/<id>` with `instance_fqdn`), which the Cloudery needs
+before it takes its members' `user.created`. Then `organization.created` is
+published on the b2b exchange, and the entry is marked. The message carries
+the organization's id, address, domain, and its name as `organization`, read
+from `--twake-instance-organization-name-attribute`, which
+`ensureOrganization` fills from `name` when the entry has none. The mark, not
+the address, says the organization is done.
+
+With the Cloudery, a member's `user.created` waits for its organization's: a
+member under an organization entry that is not marked yet gets its address
+but no event and no mark. A member outside its organization entry is not
+held, since nothing would find it to release it: it is announced with a
+warning, and needs sending again once the organization is linked. A stored
+address the provider does not confirm keeps a member held, with a warning,
+until `ensureInstance` sends it. Once the organization is
+marked, every member under its entry with an address and no mark gets its
+`user.created`, each on its own: one that fails is logged, the others are
+still sent, and the message is redelivered. A stored address is sent only
+if it is the one the provider gives the account, or once the provider
+confirms it. Nothing of this is kept in memory: the organization's
+`workplace.created` again, or `ensureOrganization` on a marked organization,
+links the organization again and sends whatever is still held, from any
+replica. That also links an organization marked before the link existed.
+
+The Cloudery builds no member instance for an organization it does not
+have. Before asking for a member's instance, the plugin asks for its
+organization and the organization's instance when the Cloudery has neither,
+so making sure of a member also repairs an organization whose creation
+failed.
+
+## Providers
+
+- `cloudery`: the Cloudery accepts the request and builds the instance
+  afterwards. An instance already at the account's address is taken when it
+  is this account's, so a re-created account keeps its instance. The address
+  arrives with `workplace.created`, consumed on `--twake-instance-queue`,
+  with a dead-letter queue. The message goes to an organization when its
+  `twakeId` is an organization id and its `internalEmail` that
+  organization's own (`<id>@<domain>`); otherwise to the account with that
+  `internalEmail`.
+- `cozy-stack`: the admin API builds the instance before answering, and the
+  address is written in the request. The instance's onboarding is marked as
+  finished, so its first login does not open the setup wizard. An instance
+  already there is taken only when its email and OIDC id are this account's.
+
+The instance id is `--twake-instance-id`, a template of the account's `uid`
+and the named groups of the matching DN expression, for example
+`{uid}{org}`; dots are dropped. A name no expression captures stops the
+server at startup. It is the slug of the instance's address; the OIDC id is
+this slug with the Cloudery, and the `uid` with cozy-stack. `user.created`
+names the account by its `uid` (`twakeId`). A group named `org` is the organization id sent to the provider
+and in `user.created`, with the mail's domain as its domain; with cozy-stack
+and no such group, `--twake-instance-cozy-org-id` and
+`--twake-instance-cozy-org-domain` stand for them.
+
+## Configuration
+
+```bash
+--plugin core/twake/instances \
+--twake-instance-dn '^uid=(?<uid>[^,]+),ou=users,ou=(?<org>[^,]+),ou=organizations,dc=example,dc=com$' \
+--twake-instance-id '{uid}{org}' \
+--twake-instance-skip-attribute employeeType \
+--twake-instance-skip-value technical \
+--twake-instance-provider cloudery \
+--twake-instance-cloudery-url https://manager.example.com \
+--twake-instance-cloudery-token … \
+--twake-instance-cloudery-domain example.com \
+--twake-instance-cloudery-organization-offer organization \
+--twake-instance-organization-base ou=organizations,dc=example,dc=com
+```
+
+A DN holds commas, so in `DM_TWAKE_INSTANCE_DN` end each expression with `;`.
+Every option and its default is listed in the
+[configuration reference](../../configuration.md). The plugin needs
+`--rabbitmq-url`.
+
+The directory schema must define the address and mark attributes, and with
+`--twake-instance-organization-base` the organization domain (and address)
+attributes: the defaults `twakeWorkspaceUrl`, `twakeCreatedEventAt` and
+`twakeDomain` come from the Twake schema, which this repository does not
+ship. The server refuses to start when one is missing.