ldap-rest 0.12.0 → 0.13.1

package/dist/src/plugins/twake/groups.d.ts

@@ -0,0 +1,89 @@
+import type { Express } from 'express';
+import type { DM } from '../../bin';
+import type { Schema } from '../../config/schema';
+import type { Hooks } from '../../hooks';
+import type { AttributeValue } from '../../lib/ldapActions';
+import LdapGroups from '../ldap/groups';
+import { type LifecycleAttributes } from './lifecycleAttributes';
+/** The values of an attribute, whatever shape the directory gave them. */
+export declare function values(value: AttributeValue | undefined): string[];
+export default class TwakeGroups extends LdapGroups {
+    name: string;
+    protected readonly groupBase: string;
+    protected readonly userBase: string;
+    protected readonly groupPattern: RegExp;
+    protected readonly attrs: LifecycleAttributes;
+    private readonly orgPattern;
+    private readonly displayName;
+    private readonly color;
+    private readonly createdAt;
+    private readonly maxPage;
+    private readonly memberFields;
+    constructor(server: DM);
+    /**
+     * Declare the group attributes under their configured names, whatever case
+     * the schema spells them in, or add them when it does not: the schema does
+     * not have to follow a renamed attribute.
+     */
+    protected adaptSchema(schema: Schema): Schema;
+    /**
+     * No `ldapdeletedone`: an erased member leaves its groups through the
+     * directory's referential integrity, whatever made the delete. The cleanup
+     * inherited from core/ldap/groups writes through LDAP-Rest, so every group
+     * would announce a member removed on an erase, which publishes nothing.
+     */
+    hooks: Hooks;
+    /**
+     * The id a `scimgroupcreate` hook assigns names the entry only when the
+     * SCIM group mapping leaves the RDN attribute alone.
+     */
+    afterLoad(): void;
+    /** The organization a group DN belongs to, if it is a group at all. */
+    organizationOf(dn: string): string | undefined;
+    groupBaseOf(org: string): string;
+    userBaseOf(org: string): string;
+    /**
+     * A group's members belong to its organization, as a provider is trusted
+     * within its own organization only. The placeholder belongs to none.
+     */
+    private checkMembers;
+    /**
+     * A tombstone keeps its memberships until it is erased, and is hidden from
+     * them, so every API reads the same member list.
+     */
+    private hideTombstones;
+    private tombstonesOf;
+    /**
+     * Only the organization routes: the flat `/v1/ldap/groups` of
+     * core/ldap/groups would read one base that holds no group here.
+     */
+    api(app: Express): void;
+    private groupDn;
+    private get userAttribute();
+    /** Every route answers 404 for a missing organization, 410 for a deleted one. */
+    private checkOrganization;
+    /** Page, search and sort of a list route, or a refusal of them. */
+    private page;
+    private sorted;
+    /** A group as the routes answer it: members named by their RDN value. */
+    private groupOf;
+    private groups;
+    private readGroup;
+    /** The group of that display name in the organization, if any. */
+    private named;
+    /** A write to a group that is not there answers 404. */
+    private onGroup;
+    private listRoute;
+    private createRoute;
+    private updateRoute;
+    private membersRoute;
+    /**
+     * Users of the organization by name, read in pages of the size limit. A
+     * tombstone is no user: it cannot be added, as it would join hidden.
+     */
+    private users;
+    private profiles;
+    private addMembersRoute;
+    private dropPlaceholder;
+    private removeMemberRoute;
+}

package/dist/src/plugins/twake/instances.d.ts

@@ -60,11 +60,24 @@ export default class TwakeInstances extends DmPlugin {
         name: string;
         domain: string;
     }): Promise<'ready' | 'pending'>;
+    private organizationRequest;
+    /**
+     * The Cloudery builds no member instance for an organization it does not
+     * have, so a member asks for a missing one first. The organization is
+     * marked when its own workplace.created arrives. Not serialized on the
+     * organization: its work releases members, which would wait on this one.
+     */
+    private requestOrganization;
     onWorkplaceCreated(message: WorkplaceCreated): Promise<void>;
+    private settle;
     /** Find the instance, or ask for it; write it down once it exists. */
     private provide;
     protected ready(dn: string, entry: AttributesList, account: Account, fqdn: string, req?: Request): Promise<void>;
     private organizationReady;
+    /** Send the user.created held while the organization at `dn` was pending */
+    private releaseMembers;
+    /** Announce a held member, with the address rule ensureInstance applies */
+    private release;
     /**
      * Run `work` once the work already queued for `key` is over. One replica
      * only: across replicas, `user.created` may still be sent twice.
@@ -72,6 +85,7 @@ export default class TwakeInstances extends DmPlugin {
     private serialized;
     private get organizationId();
     private get organizationDomain();
+    private get organizationName();
     private get organizationFqdn();
     private organizationMail;
     private isOrganization;

package/dist/src/plugins/twake/lifecycleEvents.d.ts

@@ -1,14 +1,21 @@
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import type { Hooks } from '../../hooks';
-export declare const LIFECYCLE_EVENTS: readonly ["created", "roleChanged", "disabled", "enabled", "deleted"];
+export declare const LIFECYCLE_EVENTS: readonly ["created", "roleChanged", "disabled", "enabled", "updated", "memberAdded", "memberRemoved", "deleted"];
 export type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number];
-type Payload = Record<string, string>;
+declare const MEMBER_LISTS: readonly ["$members", "$added", "$removed"];
+/** A payload field listing members, each read and shaped by `fields`. */
+interface MemberList {
+    list: (typeof MEMBER_LISTS)[number];
+    fields: Record<string, string>;
+}
+type Payload = Record<string, string | MemberList>;
+type Condition = Record<string, string>;
 interface Target {
     exchange: string;
     routingKey: string;
     payload: Payload;
-    when: Payload;
+    when: Condition;
 }
 interface Rule {
     dn: RegExp;
@@ -24,6 +31,7 @@ export default class TwakeLifecycleEvents extends DmPlugin {
     };
     private readonly rules;
     private readonly attrs;
+    private readonly memberAttribute;
     constructor(server: DM);
     /**
      * core/rabbitmq connects lazily and hands back no client when it cannot:
@@ -39,6 +47,15 @@ export default class TwakeLifecycleEvents extends DmPlugin {
     private replay;
     private match;
     private onEntryChange;
+    /** The members of an entry, the group placeholder left out. */
+    private members;
+    private memberDiff;
+    /**
+     * A member list of a payload: one read per member, a tombstone left out,
+     * and a member no longer in the directory given its RDN alone.
+     */
+    private memberPayloads;
+    private readMember;
     private resolve;
     private publish;
 }

package/docs/client-development/api/rest-api.md

@@ -538,6 +538,12 @@ Retrieve all users or filter by attributes.
 - `match` - Filter value (partial match with wildcards)
 - `attribute` - Attribute name to filter on
 - `attributes` - Comma-separated list of attributes to return
+- `limit` - Return at most this many users; `X-Result-Truncated: true` then
+  says others were left out. Without it, a list longer than the directory's
+  size limit is answered `422`
+  ([details](../../usage/plugins/ldap/flat-generic.md#long-lists)). Only the
+  flat entities' lists (users and the other schema-driven entities) take
+  `limit` for now; the [groups list](#list-groups) does not.
 
 **Example Request (all users):**
 
@@ -764,6 +770,11 @@ Retrieve all groups or filter by name.
 - `match` - Filter groups by CN (supports LDAP filter format or simple string)
 - `attributes` - Comma-separated list of attributes to return
 
+This list does not take `limit` yet: `?limit=` is ignored, no
+`X-Result-Truncated` header is sent, and a list longer than the directory's
+size limit fails with `500` rather than the `422` of the
+[users list](#list-users).
+
 **Example Request (all groups):**
 
 ```bash
@@ -1046,6 +1057,7 @@ curl -X DELETE \
 | 403         | Forbidden - Insufficient permissions   |
 | 404         | Not Found - Resource doesn't exist     |
 | 409         | Conflict - Resource already exists     |
+| 422         | Unprocessable - see below              |
 | 500         | Internal Server Error                  |
 
 ### Error Response Format
@@ -1140,6 +1152,18 @@ All errors return a JSON object with an error message:
 }
 ```
 
+#### 422 Unprocessable Entity
+
+**List longer than the directory's size limit** (flat entities' lists, when
+no `limit` was given —
+[details](../../usage/plugins/ldap/flat-generic.md#long-lists)):
+
+```json
+{
+  "error": "Too many entries to list at once: the directory's size limit was exceeded. Narrow the search, or pass `limit`."
+}
+```
+
 #### 500 Internal Server Error
 
 **LDAP Connection Error:**
@@ -1202,9 +1226,15 @@ Use the correct operation type:
 - **add**: Add values to multi-valued attributes (error if already exists)
 - **delete**: Remove attributes or specific values
 
-### Pagination
+### Long Lists
 
-For large result sets, consider implementing client-side pagination or use LDAP paging (controlled server-side).
+The API has no pagination. A flat entity's list (users and the other
+schema-driven entities) takes `limit` to bound its answer, and says with
+`X-Result-Truncated: true` that entries were left out: narrow the search with
+`match` and `attribute` to reach them. Without `limit`, a list longer than the
+directory's size limit is answered `422`. See
+[long lists](../../usage/plugins/ldap/flat-generic.md#long-lists); the groups
+list does not take `limit` yet.
 
 ### Schema Validation
 

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 |
 
@@ -457,6 +457,7 @@ Automatically creates/updates/deletes applicative account entries when users are
 | `--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).
 
@@ -497,6 +498,7 @@ See [lifecycle events](plugins/integrations/lifecycle-events.md).
 | `--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).
@@ -520,6 +522,25 @@ Reads the `--twake-lifecycle-*` attributes above, and:
 
 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

@@ -62,6 +62,7 @@ Connect to external systems:
 | [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,25 @@ 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

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

@@ -18,6 +18,7 @@ Plugins for connecting LDAP-Rest to external systems.
 | [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
 

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

@@ -65,9 +65,37 @@ 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, then
-`organization.created` is published on the b2b exchange, and the entry is
-marked. The mark, not the address, says the organization is done.
+`--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