ldap-rest 0.13.4 → 0.15.0

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

@@ -1,12 +1,55 @@
-import type { Express } from 'express';
+import type { Express, Request, Response } 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 type { AttributesList, AttributeValue } from '../../lib/ldapActions';
 import LdapGroups from '../ldap/groups';
 import { type LifecycleAttributes } from './lifecycleAttributes';
+/**
+ * An attribute's first value, whatever case its name is configured in: the
+ * directory answers it under its schema's spelling.
+ */
+export declare const read: (entry: AttributesList, attribute: string) => string | undefined;
+export declare const ORG = "{org}";
+/** A refusal the routes answer as `{ error, code }`. */
+export declare class RouteError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, message: string, code: string);
+}
+export declare const notFound: (what: string) => RouteError;
+export declare const invalid: (message: string, code?: string) => RouteError;
+export declare const NAME_RULE = "name must be a non-blank string of at most 256 characters with no control characters";
+export declare function isDisplayName(name: unknown): name is string;
+/** A request without a JSON object body leaves `req.body` undefined. */
+export declare function bodyOf(req: Request): Record<string, unknown>;
+export interface Page {
+    page: number;
+    limit: number;
+    offset: number;
+    search?: string;
+    sortBy?: string;
+    desc: boolean;
+}
 /** The values of an attribute, whatever shape the directory gave them. */
 export declare function values(value: AttributeValue | undefined): string[];
+/** A DN spelled one way, to compare two spellings of it. */
+export declare function dnKey(dn: string): string;
+export declare function parentOf(dn: string): string;
+/** The RDN value of a DN, unescaped, or the DN itself if it has none. */
+export declare function rdnValue(dn: string): string;
+/**
+ * The entries one level under a DN pattern holding `{org}`, the organization
+ * captured as one RDN value: `(?:\\.|[^,])+` keeps an escaped comma inside it.
+ */
+export declare function branchPattern(base: string): RegExp;
+/**
+ * The organization a rename moves an entry into, under a branch pattern, if
+ * it changes the entry's parent: what it holds comes along unchecked.
+ */
+export declare function movedInto(pattern: RegExp, dn: string, newDn: string): string | undefined;
+/** The organization of an entry one level under a branch pattern. */
+export declare function organizationIn(pattern: RegExp, dn: string): string | undefined;
 export default class TwakeGroups extends LdapGroups {
     name: string;
     protected readonly groupBase: string;
@@ -17,7 +60,7 @@ export default class TwakeGroups extends LdapGroups {
     private readonly displayName;
     private readonly color;
     private readonly createdAt;
-    private readonly maxPage;
+    readonly maxPage: number;
     private readonly memberFields;
     constructor(server: DM);
     /**
@@ -47,27 +90,36 @@ export default class TwakeGroups extends LdapGroups {
      * within its own organization only. The placeholder belongs to none.
      */
     private checkMembers;
+    /** A member that is not a user of the organization, if any. */
+    private foreign;
     /**
      * 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;
+    /**
+     * Read without a request: hiding a tombstone is integrity, not data, and
+     * must not depend on what the caller may see.
+     */
+    tombstonesOf(org: string): Promise<string[]>;
     /**
      * 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();
+    /** A route of the organization `:id`; see `RouteError` for refusals. */
+    organizationRoute(context: string, handler: (req: Request, res: Response, org: string) => Promise<void>, plugin?: string): (req: Request, res: Response) => Promise<void>;
+    groupDn(org: string, id: string): string;
+    get userAttribute(): string;
+    userDn(org: string, username: string): string;
     /** 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;
+    page(req: Request, sortable: string[]): Page;
+    sorted<T extends Record<string, unknown>>(items: T[], sortBy: string | undefined, desc: boolean): T[];
     /** A group as the routes answer it: members named by their RDN value. */
-    private groupOf;
-    private groups;
+    groupOf(org: string, entry: AttributesList): Record<string, unknown>;
+    groups(org: string, filter: string, attributes?: string[], req?: Request): Promise<AttributesList[]>;
     private readGroup;
     /** The group of that display name in the organization, if any. */
     private named;
@@ -77,12 +129,20 @@ export default class TwakeGroups extends LdapGroups {
     private createRoute;
     private updateRoute;
     private membersRoute;
+    /**
+     * A page of members' public profiles, each with what `extra` adds for its
+     * username.
+     */
+    memberPage(p: Page, org: string, names: string[], extra?: (username: string) => Record<string, unknown>, req?: Request): Promise<{
+        members: Record<string, unknown>[];
+        pagination: Record<string, number | boolean>;
+    }>;
     /**
      * 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;
+    users(org: string, usernames: string[], attributes: string[], req?: Request): Promise<AttributesList[]>;
+    profiles(org: string, usernames: string[], req?: Request): Promise<Map<string, Record<string, unknown>>>;
     private addMembersRoute;
     private dropPlaceholder;
     private removeMemberRoute;

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

@@ -76,14 +76,6 @@ export default class TwakeInstances extends DmPlugin {
     private provide;
     protected ready(dn: string, entry: AttributesList, account: Account, fqdn: string, req?: Request): Promise<void>;
     private organizationReady;
-    /** The organization whose account `dn` is, if it is one */
-    private organizationOf;
-    /**
-     * An organization account added once its organization is announced. One
-     * added before is filled by organizationReady
-     */
-    private giveOrganizationAddress;
-    private fillOrganizationAccount;
     /** Send the user.created held while the organization at `dn` was pending */
     private releaseMembers;
     /** Announce a held member, with the address rule ensureInstance applies */

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

@@ -0,0 +1,186 @@
+import type { Express } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
+/** From the weakest to the strongest. */
+export declare const SPACE_ROLES: readonly ["viewer", "editor", "admin"];
+export type SpaceRole = (typeof SPACE_ROLES)[number];
+export type Space = {
+    id: string;
+    name: string;
+    organizationId: string;
+    members: {
+        username: string;
+        role: SpaceRole;
+    }[];
+    groups: {
+        id: string;
+        role: SpaceRole;
+    }[];
+};
+export default class TwakeSpaces extends DmPlugin {
+    name: string;
+    roles: Role[];
+    dependencies: Record<string, string>;
+    private readonly spaceBase;
+    private readonly spacePattern;
+    private readonly userPattern;
+    private readonly lifecycle;
+    private readonly displayName;
+    readonly roleAttributes: Record<SpaceRole, string>;
+    private readonly userRole;
+    private readonly exchange;
+    /**
+     * Changes are followed one at a time, each from the directory as it is
+     * then, so the order they are followed in does not matter.
+     */
+    private following;
+    private publishing;
+    /**
+     * The spaces of a group being deleted, by DN key, read before refint takes
+     * it out of them, until its deletion is followed. `op` is the delete
+     * still running, `owed` the unlinks space writes left to it meanwhile.
+     */
+    private readonly unlinking;
+    /**
+     * The groups a deletion announced unlinked, by space DN key, until a write
+     * of the space takes their DN out of it, or finds it gone already.
+     */
+    private readonly announced;
+    /**
+     * The spaces a user being deleted is an admin of, by operation and DN,
+     * read before refint takes the user out of them.
+     */
+    private readonly handing;
+    constructor(server: DM);
+    /** Whether user roles are kept or events published. */
+    private get follows();
+    private get groups();
+    private get tombstone();
+    hooks: Hooks;
+    /**
+     * core/rabbitmq connects lazily and hands back no client when it cannot:
+     * every event would then be lost, so the server does not start.
+     *
+     * core/ldap/trash moves a deleted group or space away instead of deleting
+     * it: nothing follows the move, so users would keep the roles it gave,
+     * and no event would say it went.
+     */
+    assertComposition(): Promise<void>;
+    private queue;
+    /** The organization a space DN belongs to, if it is a space at all. */
+    organizationOf(dn: string): string | undefined;
+    spaceBaseOf(org: string): string;
+    spaceDn(org: string, id: string): string;
+    /** An entry as it is, read for no one, or nothing for one missing. */
+    private entry;
+    /** A space holds users and groups of its organization, whichever API writes it. */
+    private checkHolders;
+    /** A holder that is neither a user nor a group of the organization. */
+    private foreign;
+    api(app: Express): void;
+    /** A space as the routes answer it, strongest role first. */
+    private spaceOf;
+    /**
+     * The users and groups an entry holds, strongest role first, each once
+     * with its strongest role. A tombstone is hidden.
+     */
+    private entryOf;
+    /** The spaces of the organization matching a filter, or the one of an id. */
+    private spaces;
+    /**
+     * Whoever asks: a tombstone outside the caller's branches would otherwise
+     * count as a member, and as an admin.
+     */
+    private hidden;
+    /** A filter for the spaces holding any of these DNs, whatever the role. */
+    private holding;
+    private space;
+    private write;
+    /**
+     * A change decided on a space read before another request wrote it fails
+     * with LDAP 16 or 20: it is decided again on the space as it is now.
+     */
+    private again;
+    /** The live users of the organization by lowercased name, as DNs, or a 404. */
+    private liveUsers;
+    private get groupName();
+    /** Groups of the organization by id, read in pages of the size limit. */
+    private orgGroups;
+    /**
+     * The users a space write or a change of a group's members may have
+     * moved, and the events of the write. A deleted group is followed through
+     * its members as they were.
+     */
+    private follow;
+    /**
+     * The spaces a user is an admin of. Read again when a tombstone is erased:
+     * its hand-over may have failed, or predate this plugin, and handing over
+     * a space that keeps another admin does nothing.
+     */
+    private administered;
+    /**
+     * A space a deleted user was the last admin of goes to its editors, else
+     * its viewers; one left with no member is deleted.
+     */
+    private handOver;
+    private handOverOnce;
+    /** A group about to be deleted, if it is one linked to spaces. */
+    private deletedGroup;
+    /**
+     * The spaces a deleted group left. One still holding its DN, without
+     * refint, remembers the announcement for the write that takes it out.
+     */
+    private unlinked;
+    /**
+     * Rewrite each user's roles from the directory as it is now: a change
+     * only tells which users to look at, so two changes followed in either
+     * order, or late, leave the same roles.
+     *
+     * The roles each user had come from the values written before, or, with
+     * no user role attribute, from the directory with the change undone: two
+     * changes followed late may then announce a role twice, or not at all.
+     */
+    private settle;
+    /**
+     * A filter for the spaces a user is in, directly or through a group, and
+     * their role in one of them. With a group's members undone, as they were.
+     */
+    private userIn;
+    /**
+     * The events of a followed change: the space write itself, then each
+     * moved user's roles, except in a space created or deleted by it.
+     *
+     * A role may have moved in a space the change did not touch, by another
+     * change not followed yet. Without the role attribute, that change
+     * announces it. With it, this follow wrote the value, so that change
+     * will find nothing to announce: the role goes out here, without an
+     * actor, as this change's is not the one that moved it.
+     */
+    private announce;
+    /** Users as space events name them, by DN key, live users only. */
+    private profiles;
+    private publishEvent;
+    private get rabbitmq();
+    private publish;
+    /** A user's roles, in the directory as it is or with a change undone. */
+    private rolesOf;
+    /**
+     * Write a user's `<space id>:<role>` values, and answer the roles they
+     * held, or nothing for a user gone.
+     */
+    private writeRoles;
+    /** The groups of the organization by lowercased id, as DNs, or a 404. */
+    private groupDns;
+    /** Each of a space's members or groups holds one role. */
+    private add;
+    private addOnce;
+    /**
+     * Move a member or group to another role, or out of the space without
+     * one. A space keeps at least one admin among its users.
+     */
+    private change;
+    private changeOnce;
+    private listRoute;
+    private createRoute;
+}

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

@@ -53,6 +53,11 @@ export default class TwakeTombstone extends DmPlugin {
         force?: boolean;
         req?: Request;
     }): Promise<void>;
+    /**
+     * Whether a delete of this DN, asked for now, writes a tombstone instead of
+     * reaching the directory: not when it erases one.
+     */
+    keeps(dn: string): boolean;
     /**
      * core/ldap/trash moves a deleted entry away before this plugin, last in
      * the delete chain, sees it: no tombstone would be written, and an erase

package/docs/plugin-development/README.md

@@ -690,6 +690,27 @@ api(app: Express): void {
 }
 ```
 
+#### Parsing request bodies
+
+The server parses `application/json` (up to 100 kB) and
+`application/x-www-form-urlencoded` bodies before authentication runs, so
+that `core/auth/hmac` can check them. A plugin that needs another media type
+or limit under its prefix registers its own parser, which runs ahead of
+those:
+
+```typescript
+import { jsonBodyParser } from '../../lib/rawBody';
+
+api(app: Express): void {
+  this.server.registerBodyParser('/myplugin', jsonBodyParser({ limit: '1mb' }));
+}
+```
+
+`jsonBodyParser` keeps the bytes it reads, which `core/auth/hmac` hashes. Any
+other parser must pass `keepRawBody` as `verify`, or `core/auth/hmac` refuses
+its bodies with `401`. A parser mounted with `app.use()` in `api()` runs
+after authentication, too late for that check.
+
 #### Error Handling Best Practices
 
 The `asyncHandler` wrapper automatically catches errors and passes them to the global error middleware. This ensures:

package/docs/plugin-development/hooks.md

@@ -19,6 +19,9 @@ Typescript definitions into [hooks.ts](./src/hooks.ts)
 - **ldapmodifyrequest**: called before any ldapmodify
 - **ldapdeleterequest**: called before any ldapdelete
 - **ldaprenamerequest**: called before any ldap rename/modifyDN operation
+- **ldapmodifyend**, **ldapdeleteend**, **ldaprenameend**: launched once a
+  modify, delete or rename is over, whatever became of it, see
+  [below](#ldapmodifyend-ldapdeleteend-ldaprenameend)
 
 ### ldapaddafter
 
@@ -41,6 +44,28 @@ the account the entry describes.
   no set order with it: an add event may or may not include what a
   subscriber here wrote.
 
+### ldapmodifyend, ldapdeleteend, ldaprenameend
+
+For a plugin that keeps something from a request hook to the matching "done"
+one, as core/ldap/onChange keeps the entry it read. A write that is refused
+by a request hook, that one of them takes out of the request (core/ldap/trash
+and core/twake/tombstone do with a delete), or that the directory refuses,
+never reaches its "done" hook; its "end" hook fires all the same.
+
+- Each gets the number of its operation. A modify's request and "done" hooks
+  are given it in their arguments; for every modify, delete and rename,
+  `currentOperation()` (`lib/operation`) returns it inside the request and
+  "done" hooks. Key what you keep by it rather than by DN: two writes of one
+  DN may be under way, and only the operation tells them apart.
+  Outside those hooks it is whatever encloses the call (an add made from a
+  delete's request hook sees the delete's number): in an end hook, use the
+  number it is given.
+- It is launched once the "done" subscribers of the operation have returned,
+  and is not awaited by the write.
+- A move (`ldapActions.move`) launches no request hook and no end hook, and
+  its `ldaprenamedone` runs outside any operation, even when a request hook
+  made it.
+
 ## [onChange](../usage/plugins/ldap/on-change.md) hooks
 
 - **onLdapEntryChange**: called after any write, with the entry before and

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
 
@@ -500,7 +561,6 @@ See [lifecycle events](plugins/integrations/lifecycle-events.md).
 | `--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) |
-| `--twake-instance-organization-account`          | `DM_TWAKE_INSTANCE_ORGANIZATION_ACCOUNT`          |                                       | Organization account DN, `{id}` its id (empty: none)      |
 
 See [instances](plugins/integrations/instances.md).
 
@@ -542,6 +602,25 @@ 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`.
+
+| 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                 |
+
+See [spaces](plugins/integrations/spaces.md).
+
 ### Utility Plugins
 
 #### `core/static`

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

@@ -60,8 +60,13 @@ DM_AUTH_HMAC_WINDOW=120000  # Default: 120000ms (2 minutes)
 
    Only a body the server parses before checking the signature can be signed:
    `application/json`, `application/x-www-form-urlencoded` and, under the
-   SCIM prefix, `application/scim+json`. A POST, PATCH or PUT carrying any other body,
+   prefix of a loaded `core/scim`, `application/scim+json`. A POST, PATCH or PUT carrying any other body,
    such as a `multipart/form-data` bulk import upload, is refused with `401`.
+   So is a GET, DELETE or HEAD carrying a body, since they are signed without
+   one.
+
+   The `Content-Type` is not part of the signature. A signed body is read as
+   UTF-8 only: one sent under another `charset` is refused with `401`.
 
 2. **Client sends Authorization header:**
 

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,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/instances.md

@@ -75,16 +75,6 @@ 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.
 
-`--twake-instance-organization-account` names an account of the
-organization by a DN template, `{id}` standing for the organization id, for
-example `uid={id},ou=users,ou={id},ou=organizations,dc=example,dc=com`. It
-is usually a technical account, kept from an instance of its own by
-`--twake-instance-skip-attribute`. When the organization is announced, and on
-any replay, the account gets the organization's address in
-`--twake-instance-fqdn-attribute`, when it exists and has none. An account
-added once the organization is marked gets it at creation, read from the
-organization entry or else from the provider.
-
 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

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: