ldap-rest 0.11.2 → 0.12.0

package/docs/usage/plugins/README.md

@@ -53,12 +53,15 @@ 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  |
 
 ## Utility Plugins
 

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

@@ -85,6 +85,33 @@ 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.
 
+## 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,13 @@ 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      |
 
 ## Prerequisites
 
@@ -39,4 +42,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/instances.md

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

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

@@ -0,0 +1,200 @@
+# Lifecycle Events
+
+`core/twake/lifecycleEvents` publishes an account's lifecycle to RabbitMQ from
+the directory write itself. REST, SCIM and any other plugin writing through
+LDAP-Rest announce the same events, with the same payloads.
+
+Which entries are accounts, which attributes carry the role, the lock and the
+deletion, and where each event goes are configuration.
+
+## Events
+
+Each event is a change of state, read from the entry before and after a write
+(`onLdapEntryChange`, from `core/ldap/onChange`). A write that changes nothing
+publishes nothing.
+
+- `created`: an entry is added. An entry added locked, as a SCIM create with
+  `active: false` does, publishes `created` then `disabled`.
+- `roleChanged`: the role attribute gets different values. Case and order are
+  ignored: `Admin` and `admin` are one role. A multi-valued role attribute is
+  compared as a set, but `$title` carries its first value only, so
+  `[x, y]` to `[x, z]` publishes `x` as both role and previous role: keep the
+  role in a single-valued attribute.
+- `disabled`: the lock attribute takes the lock value.
+- `enabled`: the lock attribute no longer holds the lock value.
+- `deleted`: the entry becomes a tombstone (the deleted attribute takes the
+  deleted value), or an entry that is not a tombstone is removed.
+
+An account is locked when its lock attribute holds the lock value, by default
+the ppolicy administrative lock `000001010000Z`. Any other value, such as the
+timestamp of a ppolicy lockout after failed binds, is not a lock here.
+
+A tombstone announces nothing else: the write that makes it does not also
+publish `disabled`, later changes to it (a lock written afterwards included)
+publish nothing, and removing it publishes nothing, since its deletion was
+already announced.
+
+A publish that fails is logged as an error, and the next targets are still
+published. It never fails the write that caused it, and the event is not
+replayed: writing the same value again changes nothing, so it publishes
+nothing. With `core/twake/tombstone`, a lost `deleted` is published again by
+deleting the tombstone once more (see below); a lost `disabled`, `enabled`,
+`created` or `roleChanged` has no such path.
+
+The lock attribute is requested by name when the entry is read, so an
+operational one such as `pwdAccountLockedTime` is seen on both sides.
+
+## What is not published
+
+- A rename or a move publishes nothing. The `$dn.*` groups of the new DN may
+  then differ from the ones consumers know, and an entry moved into or out of
+  a rule's pattern publishes neither `created` nor `deleted`.
+- A tombstone cannot be restored. Clearing its deleted attribute is not a
+  supported operation: it publishes nothing, whatever else the same write
+  changes, and later changes are published again as for any account, to
+  consumers that consider it deleted.
+- A change made outside LDAP-Rest is not seen. A ppolicy lockout after failed
+  binds is written by the directory itself, and holds a timestamp rather than
+  the lock value: it publishes nothing, and neither does clearing it.
+
+## Deployments with other plugins
+
+- `core/twake/tombstone` answers a second delete of a tombstone without
+  writing anything, and fires `twakedeletionreplay`; this plugin then
+  publishes `deleted` again, with the tombstone as it is (same deletion date).
+  This explicit delete is how a `deleted` event a broker outage lost is
+  replayed.
+- `core/twake/cozyProvision` and `core/twake/clouderyProvision` publish their
+  own deletion event on `--cozy-user-deleted-routing-key`. When a `deleted`
+  rule here publishes it, set that option to `""`. Turning it off without a
+  `deleted` rule leaves no deletion event at all; keeping both publishes it
+  twice.
+- `core/ldap/trash` moves a deleted entry instead of removing it, and a move
+  made by the trash is not seen by `core/ldap/onChange`. A deletion in a
+  branch the trash watches publishes nothing.
+
+## Configuration
+
+```bash
+--plugin core/twake/lifecycleEvents \
+--twake-lifecycle-role-attribute title \
+--twake-lifecycle-lock-attribute pwdAccountLockedTime \
+--twake-lifecycle-lock-value 000001010000Z \
+--twake-lifecycle-deleted-attribute employeeType \
+--twake-lifecycle-deleted-value deleted \
+--twake-lifecycle-deleted-at-attribute roomNumber \
+--twake-lifecycle-deleted-at-format iso8601 \
+--twake-lifecycle-rules /etc/ldap-rest/lifecycle-rules.json
+```
+
+- `--twake-lifecycle-role-attribute`: empty means no `roleChanged`.
+- `--twake-lifecycle-lock-attribute`, `--twake-lifecycle-lock-value`: default
+  to `--scim-user-lock-attribute` and `--scim-user-lock-value`, so SCIM
+  `active` and the events agree; SCIM's value only goes with SCIM's
+  attribute. `pwdAccountLockedTime` defaults to `000001010000Z`; any other
+  attribute needs its value, or the server does not start, as for
+  [SCIM](scim.md).
+  Only changes written through LDAP-Rest are seen: a lockout set by the
+  directory publishes nothing.
+- `--twake-lifecycle-deleted-attribute`, `--twake-lifecycle-deleted-value`
+  (default `TRUE`, compared case-insensitively): what marks a tombstone. Empty
+  means entries are never tombstones, and only a removal publishes `deleted`.
+- `--twake-lifecycle-deleted-at-attribute`,
+  `--twake-lifecycle-deleted-at-format` (`iso8601`, the default, or
+  `generalizedTime`): the deletion date. It is always published as ISO 8601.
+- `--twake-lifecycle-rules`: a JSON file, or the JSON itself.
+
+Each option has a `DM_` environment variable, for example
+`DM_TWAKE_LIFECYCLE_RULES`. The events go through `core/rabbitmq`. With rules
+configured, the server does not start without `--rabbitmq-url`, nor when
+that broker cannot be reached. An event that finds no broker later on is
+lost, and logged as an error.
+
+## Rules
+
+The rules are an array. The first rule whose `dn` regular expression matches
+the entry's DN (case-insensitively) decides what is published; an entry no
+rule matches publishes nothing.
+
+The DN is matched without spaces around its separators, and with escaped
+commas written `\2C`: `uid=a\, b, ou=users,…` is read as `uid=a\2C b,ou=users,…`,
+so `(?<id>[^,]+)` takes the whole value. A `$dn.name` group is unescaped:
+`a, b`.
+
+```json
+[
+  {
+    "dn": "^uid=(?<id>[^,]+),ou=users,dc=example,dc=com$",
+    "exchange": "accounts",
+    "payload": {
+      "id": "$dn.id",
+      "email": "$mail",
+      "domain": "$mail|domain",
+      "role": "$title",
+      "timestamp": "$now"
+    },
+    "events": {
+      "created": "account.created",
+      "roleChanged": {
+        "routingKey": "account.role.changed",
+        "payload": {
+          "id": "$dn.id",
+          "role": "$title",
+          "previousRole": "$previous.title"
+        }
+      },
+      "disabled": "account.disabled",
+      "enabled": "account.enabled",
+      "deleted": [
+        "account.deleted",
+        {
+          "exchange": "notifications",
+          "routingKey": "account.deleted",
+          "when": { "$businessCategory": "user_request" },
+          "payload": { "id": "$dn.id", "mobile": "$previous.mobile" }
+        }
+      ]
+    }
+  }
+]
+```
+
+An event takes one target or a list of them, published in order. A target is
+a routing key, or an object with:
+
+- `routingKey`
+- `exchange`: defaults to the rule's
+- `payload`: replaces the rule's `payload`
+- `when`: publish only if every source equals its value; a value starting with
+  `!` means "differs from"
+
+Payload and `when` values are sources:
+
+- `$attr`: the attribute after the write; for a removed entry, which has no
+  "after", the attribute before it
+- `$previous.attr`: the attribute before the write
+- `$dn.name`: a named group of the rule's `dn` expression
+- `$context.actor`, `$context.requestId`, `$context.source`: who made the
+  write, the request it belongs to, and the API it came through (`rest`,
+  `scim`); left out for a write no request made, such as a scheduled task
+- `$attr|domain`, `$previous.attr|domain`: what follows the `@`
+- `$now`: the current time, ISO 8601
+- 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. Every message carries
+a random AMQP `messageId`.
+
+A source can read any attribute of the entry: `$userPassword` would put the
+password hash in the message.
+
+The rules are checked at startup: a malformed one, such as a payload value
+that is not a string, stops the server with an error naming its `dn`.
+
+## Dependencies
+
+```
+core/twake/lifecycleEvents
+  ├─ requires: core/ldap/onChange
+  └─ requires: core/rabbitmq
+```

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

@@ -305,6 +305,17 @@ mapping contains an entry with `scim: "department"`; otherwise the server return
 `400 invalidFilter`. Same for PATCH: operations on unmapped paths produce
 `400 invalidPath`.
 
+A PATCH `add`, or a `remove` naming values, changes only the values it names:
+values the caller's read did not show, such as group members an
+`ldapsearchfilter` hides, stay. Two PATCHes changing different values of
+the same attribute both apply. Adding a value already there succeeds where
+the directory honours the permissive modify control; removing one another
+write just removed replays the PATCH on a fresh read, then answers `409`.
+A `replace`, or a `remove` of a whole attribute, sets the attribute to what
+the caller sent, and so does a group `PUT` for its members, hidden ones
+included. A group left with no member the caller saw gets the
+`--group-dummy-user` placeholder.
+
 ### Schema advertisement
 
 Schemas listed under `GET /scim/v2/Schemas` are read from

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

@@ -0,0 +1,115 @@
+# Tombstone
+
+`core/twake/tombstone` turns the delete of an account into a tombstone. The
+entry stays, so its identifiers cannot be taken by a new account, but it is
+flagged as deleted, dated, locked, carries the reason, and loses the
+attributes the deployment names.
+
+A tombstone is erased later, from an operator's decision: once the deletion
+is old enough, or right away when forced.
+
+## Behaviour
+
+- A delete of an entry whose DN matches `--twake-tombstone-dn` writes, in one
+  modify: the deleted attribute, the deletion date (now), the reason, the
+  lock, and removes `--twake-tombstone-clear-attributes`. Other entries are
+  deleted as usual.
+- A delete of an existing tombstone writes nothing and answers as a delete.
+  It fires the `twakedeletionreplay` hook with the tombstone, so
+  [lifecycle events](lifecycle-events.md) publishes the deletion again, with
+  the date of the first one. This is the way to replay a `deleted` event that
+  was lost, for instance while the broker was down.
+- The tombstone is written by the server, not as the caller: the caller's
+  delete right is what was judged, and a write right is not required on top.
+  So the `deleted` event of that write has no `$context.actor`,
+  `$context.requestId` or `$context.source`. A replay has them.
+- The tombstone keeps its group memberships until it is erased.
+- SCIM treats a tombstone as gone: reads answer 404, lists leave it out, and
+  a create with the same identity erases the tombstone and creates a new
+  entry. If the directory then refuses the new entry, the tombstone and its
+  memberships are put back once the response is sent.
+- Erasing removes the entry, then its group memberships. It publishes
+  nothing.
+- A tombstone cannot be restored. Clearing its deleted attribute by hand is
+  not a supported operation.
+
+The tombstone is written after every other plugin has judged the delete, so
+a delete that an authorization plugin refuses writes nothing.
+
+`core/ldap/trash` moves a deleted entry before this plugin sees the delete,
+so no tombstone would be written in a branch it watches. The server refuses
+to start when `--trash-watched-bases` covers a `--twake-tombstone-dn`
+pattern, read the way the trash reads it today, and an empty list watches
+every branch.
+
+The trash splits `--trash-watched-bases` on every comma, a bug
+([#226](https://github.com/linagora/ldap-rest/issues/226)): a base such as
+`ou=users,dc=example,dc=com` becomes the suffixes `ou=users`, `dc=example`
+and `dc=com`, and `dc=com` watches every branch below it. The check follows
+the trash as it behaves, so such a value refuses to start next to any
+tombstone pattern under `dc=com`.
+
+## Reason
+
+The reason is, in order:
+
+- the one given to `tombstone(dn, reason, req)` by another plugin;
+- the `--twake-tombstone-reason-header` request header;
+- `--twake-tombstone-default-reason`.
+
+When `--twake-tombstone-reasons` is set, any other reason is refused with a 400. Otherwise a reason is letters, digits, `_`, `.` or `-`.
+
+## Erase
+
+```http
+POST /api/v1/twake/tombstones/erase
+Content-Type: application/json
+
+{ "dn": "uid=jdoe,ou=users,dc=example,dc=com", "force": false }
+```
+
+- `200`: erased.
+- `404`: no tombstone at this DN.
+- `409`: the deletion is younger than `--twake-tombstone-erase-min-age` and
+  `force` is not true.
+
+Other plugins call `erase(dn, { force, req })`.
+
+## Configuration
+
+The tombstone attributes are the lifecycle ones, shared with
+[lifecycle events](lifecycle-events.md):
+
+```bash
+--plugin core/twake/tombstone \
+--twake-lifecycle-lock-attribute pwdAccountLockedTime \
+--twake-lifecycle-lock-value 000001010000Z \
+--twake-lifecycle-deleted-attribute employeeType \
+--twake-lifecycle-deleted-value deleted \
+--twake-lifecycle-deleted-at-attribute roomNumber \
+--twake-lifecycle-deleted-at-format iso8601 \
+--twake-lifecycle-reason-attribute businessCategory \
+--twake-tombstone-dn '^uid=[^,]+,ou=users,dc=example,dc=com$' \
+--twake-tombstone-dn '^uid=[^,]+,ou=[^,]+,ou=organizations,dc=example,dc=com$' \
+--twake-tombstone-reasons deleted,user_request \
+--twake-tombstone-clear-attributes mobile,telephoneNumber \
+--twake-tombstone-erase-min-age 2592000 \
+--twake-tombstone-group-bases ou=groups,dc=example,dc=com
+```
+
+- `--twake-lifecycle-deleted-attribute`: required.
+- `--twake-lifecycle-lock-attribute`, `--twake-lifecycle-lock-value`: the
+  lock written on a tombstone, read as
+  [lifecycle events](lifecycle-events.md) reads it. A lock attribute other
+  than `pwdAccountLockedTime` needs its value (`TRUE` for `nsAccountLock` on
+  389-ds), or the server does not start: `000001010000Z` means nothing there.
+- `--twake-lifecycle-reason-attribute`: empty means the reason is not
+  recorded.
+- `--twake-tombstone-dn`: regular expressions, matched case-insensitively. A
+  DN holds commas, so in `DM_TWAKE_TOMBSTONE_DN` end each one with `;`.
+- `--twake-tombstone-default-reason`: default `deleted`.
+- `--twake-tombstone-reason-header`: default `x-deletion-reason`.
+- `--twake-tombstone-erase-min-age`: seconds, default 30 days.
+- `--twake-tombstone-group-bases`: where memberships are looked for at erase,
+  by `member`. Defaults to `--ldap-group-base`, then `--ldap-base`. In the
+  environment variable, end each base with `;`.

package/docs/usage/upgrading.md

@@ -4,6 +4,64 @@ What to check before deploying, newest first. Only releases that need a
 decision or a configuration change appear here; see the
 [CHANGELOG](../../CHANGELOG.md) for everything else.
 
+## To 0.12.0
+
+### twake/instances replaces cozyProvision and clouderyProvision
+
+**Who is affected:** a deployment loading `core/twake/cozyProvision` or
+`core/twake/clouderyProvision`.
+
+Replace the plugin with `core/twake/instances`
+([doc](plugins/integrations/instances.md)); the server refuses to start with
+both. Its options are its own. From cozyProvision, with
+`--twake-instance-provider cozy-stack` and `--twake-instance-dn` set to the
+accounts' branch:
+
+- `--cozy-admin-url` → `--twake-instance-cozy-url`
+- `--cozy-admin-user` → `--twake-instance-cozy-user`
+- `--cozy-admin-passphrase` → `--twake-instance-cozy-passphrase`
+- `--cozy-org-domain` → `--twake-instance-cozy-domain` (the instances'
+  domain) and `--twake-instance-cozy-org-domain`
+- `--cozy-org-id` → `--twake-instance-cozy-org-id`
+- `--cozy-context-name` → `--twake-instance-cozy-context`
+- `--cozy-apps` → `--twake-instance-cozy-apps`
+- `--cozy-default-locale` → `--twake-instance-locale`
+- `--cozy-auth-exchange` → `--twake-instance-auth-exchange`
+- `--cozy-b2b-exchange` → `--twake-instance-b2b-exchange`
+- `--cozy-user-created-routing-key` → `--twake-instance-user-created-key`
+
+From clouderyProvision, with `--twake-instance-provider cloudery`:
+
+- `--cloudery-manager-url` → `--twake-instance-cloudery-url`
+- `--cloudery-manager-token` → `--twake-instance-cloudery-token`
+- `--cloudery-offer` → `--twake-instance-cloudery-offer`
+- `--cloudery-domain` → `--twake-instance-cloudery-domain`
+- `--cloudery-default-locale` → `--twake-instance-locale`
+- `--cloudery-fqdn-attribute` → `--twake-instance-fqdn-attribute`
+- `--cloudery-user-branch` → `--twake-instance-dn`, with an `org` group for
+  the organization id; `--twake-instance-id '{uid}{org}'` keeps the slugs
+
+What no longer happens:
+
+- An account gets its instance on any add under `--twake-instance-dn`, not
+  only a SCIM create.
+- `domain.user.deleted` is not published, and `--cozy-user-deleted-routing-key`
+  has no plugin to read it. With the Cloudery, deleting an account no longer
+  deletes its instance; cozy-stack instances still are.
+- clouderyProvision's writes on a SCIM create are gone:
+  `twakeOrganizationId`, `twakeOrganizationRole`, `twakeInvited`,
+  `twakePhones`, `cn` set to the userName, and the lower-casing of the SCIM
+  `userName`. The `x-cloudery-org-*` headers are not read; the organization
+  comes from the DN. `--cloudery-org-*`, `--cloudery-phones-attribute`,
+  `--cloudery-invited-attribute` and the workflow polling options are gone:
+  the address arrives with `workplace.created` instead.
+- With cozy-stack, the instance address drops the uid's dots and lower-cases
+  it, as the Cloudery's slugs do: an account whose uid holds a dot or a
+  capital gets a different address than cozyProvision gave it. Its OIDC id
+  is still the uid.
+
+`user.created` keeps its fields, `twakeId` still being the account's uid.
+
 ## To 0.11.0
 
 ### Group reads are judged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -268,10 +268,26 @@
       "types": "./dist/src/plugins/twake/drive.d.ts",
       "import": "./dist/plugins/twake/drive.js"
     },
+    "./plugin-twake-instances": {
+      "types": "./dist/src/plugins/twake/instances.d.ts",
+      "import": "./dist/plugins/twake/instances.js"
+    },
     "./plugin-twake-james": {
       "types": "./dist/src/plugins/twake/james.d.ts",
       "import": "./dist/plugins/twake/james.js"
     },
+    "./plugin-twake-lifecycleattributes": {
+      "types": "./dist/src/plugins/twake/lifecycleAttributes.d.ts",
+      "import": "./dist/plugins/twake/lifecycleAttributes.js"
+    },
+    "./plugin-twake-lifecycleevents": {
+      "types": "./dist/src/plugins/twake/lifecycleEvents.d.ts",
+      "import": "./dist/plugins/twake/lifecycleEvents.js"
+    },
+    "./plugin-twake-tombstone": {
+      "types": "./dist/src/plugins/twake/tombstone.d.ts",
+      "import": "./dist/plugins/twake/tombstone.js"
+    },
     "./plugin-weblogs": {
       "types": "./dist/src/plugins/weblogs.d.ts",
       "import": "./dist/plugins/weblogs.js"