ldap-rest 0.11.2 → 0.12.0

package/dist/src/config/args.d.ts

@@ -210,6 +210,54 @@ export interface Config {
     cloudery_default_locale?: string;
     cloudery_workflow_poll_interval_ms?: number;
     cloudery_workflow_max_attempts?: number;
+    twake_lifecycle_role_attribute?: string;
+    twake_lifecycle_lock_attribute?: string;
+    twake_lifecycle_lock_value?: string;
+    twake_lifecycle_deleted_attribute?: string;
+    twake_lifecycle_deleted_value?: string;
+    twake_lifecycle_deleted_at_attribute?: string;
+    twake_lifecycle_deleted_at_format?: string;
+    twake_lifecycle_rules?: string;
+    twake_instance_dn?: string[];
+    twake_instance_skip_attribute?: string;
+    twake_instance_skip_value?: string;
+    twake_instance_provider?: string;
+    twake_instance_id?: string;
+    twake_instance_fqdn_attribute?: string;
+    twake_instance_sent_attribute?: string;
+    twake_instance_locale?: string;
+    twake_instance_timeout?: number;
+    twake_instance_cloudery_url?: string;
+    twake_instance_cloudery_token?: string;
+    twake_instance_cloudery_offer?: string;
+    twake_instance_cloudery_domain?: string;
+    twake_instance_cloudery_organization_offer?: string;
+    twake_instance_cozy_url?: string;
+    twake_instance_cozy_user?: string;
+    twake_instance_cozy_passphrase?: string;
+    twake_instance_cozy_domain?: string;
+    twake_instance_cozy_context?: string;
+    twake_instance_cozy_apps?: string;
+    twake_instance_cozy_org_id?: string;
+    twake_instance_cozy_org_domain?: string;
+    twake_instance_auth_exchange?: string;
+    twake_instance_b2b_exchange?: string;
+    twake_instance_user_created_key?: string;
+    twake_instance_organization_created_key?: string;
+    twake_instance_workplace_created_key?: string;
+    twake_instance_queue?: string;
+    twake_instance_organization_base?: string;
+    twake_instance_organization_id_attribute?: string;
+    twake_instance_organization_domain_attribute?: string;
+    twake_instance_organization_fqdn_attribute?: string;
+    twake_lifecycle_reason_attribute?: string;
+    twake_tombstone_dn?: string[];
+    twake_tombstone_default_reason?: string;
+    twake_tombstone_reason_header?: string;
+    twake_tombstone_reasons?: string[];
+    twake_tombstone_clear_attributes?: string[];
+    twake_tombstone_erase_min_age?: number;
+    twake_tombstone_group_bases?: string[];
     rabbitmq_url?: string;
     applicative_account_base?: string;
     max_app_accounts?: number;

package/dist/src/hooks.d.ts

@@ -51,6 +51,8 @@ export interface Hooks {
     ldapsearchfilter?: ChainedHook<[SearchResult, Request?, SearchOptions?]>;
     ldapaddrequest?: ChainedHook<[string, AttributesList, Request?]>;
     ldapadddone?: (args: [string, AttributesList], context?: ChangeContext) => MaybePromise<void>;
+    /** See docs/plugin-development/hooks.md#ldapaddafter */
+    ldapaddafter?: (args: [string, AttributesList], context?: ChangeContext) => MaybePromise<void>;
     ldapmodifyrequest?: ChainedHook<[string, ModifyRequest, number, Request?]>;
     ldapmodifydone?: (args: [string, ModifyRequest, number], context?: ChangeContext) => MaybePromise<void>;
     ldapdeleterequest?: ChainedHook<[string | string[], Request?]>;

package/dist/src/lib/authz/composition.d.ts

@@ -141,5 +141,5 @@ export declare function describePopulation(population: Population, authenticator
  *        `server.loadedPlugins`; only what concerns it is checked
  * @throws Error naming the plugins when the composition is ambiguous
  */
-export declare function assertAuthzComposition(server: DM, candidate?: DmPlugin): void;
+export declare function assertAuthzComposition(server: DM, candidate?: DmPlugin): Promise<void>;
 export {};

package/dist/src/lib/instanceProviders.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @module lib/instanceProviders
+ *
+ * The two places a workplace instance can be created: the Cloudery, which
+ * answers at once and builds the instance afterwards, and the cozy-stack
+ * admin API, which builds it before answering.
+ */
+import { type RequestInit, type Response } from 'node-fetch';
+export interface InstanceRequest {
+    /** Slug of the instance, and its OIDC id unless `oidc` says otherwise */
+    id: string;
+    oidc?: string;
+    email: string;
+    publicName: string;
+    locale: string;
+    phone?: string;
+    orgId?: string;
+    orgDomain?: string;
+    offer?: string;
+}
+export interface FoundInstance {
+    fqdn: string;
+    /** Built and usable, not only accepted */
+    ready: boolean;
+}
+export interface InstanceProvider {
+    /**
+     * Ask for an instance. Answers the address when the instance already
+     * exists by then; otherwise it comes later, with `workplace.created`.
+     */
+    create(request: InstanceRequest): Promise<string | undefined>;
+    /**
+     * The instance at this request's address, if any. One that belongs to
+     * another account is a conflict, not an answer.
+     */
+    find(request: InstanceRequest, at?: string): Promise<FoundInstance | undefined>;
+    /** The address this request's instance gets. */
+    address(request: InstanceRequest): string;
+}
+/**
+ * HTTP with a deadline per call: these calls sit inside the add request.
+ * The deadline covers the answer's body too.
+ */
+declare abstract class HttpProvider {
+    protected readonly domain: string;
+    protected readonly timeout: number;
+    constructor(domain: string, timeout: number);
+    address(request: InstanceRequest): string;
+    protected call(url: string, init?: RequestInit): Promise<Response>;
+    protected json<T>(res: Response): Promise<T>;
+    private timedOut;
+}
+export declare class ClouderyProvider extends HttpProvider implements InstanceProvider {
+    private readonly url;
+    private readonly token;
+    private readonly offer;
+    constructor(url: string, token: string, domain: string, offer: string, timeout: number);
+    private headers;
+    create(request: InstanceRequest): Promise<undefined>;
+    find(request: InstanceRequest, at?: string): Promise<FoundInstance | undefined>;
+    createOrganization(org: {
+        id: string;
+        name: string;
+        domain: string;
+    }): Promise<void>;
+}
+export declare class CozyStackProvider extends HttpProvider implements InstanceProvider {
+    private readonly url;
+    private readonly context;
+    private readonly apps;
+    private readonly auth;
+    constructor(url: string, user: string, passphrase: string, domain: string, context: string, apps: string, timeout: number);
+    private headers;
+    create(request: InstanceRequest): Promise<string>;
+    /** Also finishes the onboarding of an instance left unfinished. */
+    find(request: InstanceRequest, at?: string): Promise<FoundInstance | undefined>;
+    /**
+     * Destroy the instance of a deleted account, the entry being gone: one
+     * another OIDC id owns is left alone.
+     */
+    destroy(id: string, oidc: string): Promise<void>;
+    private read;
+    /** Without it, the first login lands on the setup wizard. */
+    private finishOnboarding;
+}
+export {};

package/dist/src/lib/ldapActions.d.ts

@@ -26,7 +26,7 @@ export type { SearchOptions, SearchResult };
 export interface RequestBoundLdap {
     search(options: SearchOptions, base?: string): Promise<SearchResult | AsyncGenerator<SearchResult>>;
     add(dn: string, entry: AttributesList): Promise<boolean>;
-    modify(dn: string, changes: ModifyRequest): Promise<boolean>;
+    modify(dn: string, changes: ModifyRequest, options?: ModifyOptions): Promise<boolean>;
     rename(dn: string, newRdn: string): Promise<boolean>;
     delete(dn: string | string[]): Promise<boolean>;
 }
@@ -35,6 +35,14 @@ export interface ModifyRequest {
     replace?: AttributesList;
     delete?: string[] | AttributesList;
 }
+export interface ModifyOptions {
+    /**
+     * Send the permissive modify control, not critical: a directory that
+     * honours it accepts an add of a value already there (OpenLDAP 2.4 still
+     * refuses a delete of an absent one); one that does not ignores it.
+     */
+    permissive?: boolean;
+}
 declare class ldapActions {
     config: Config;
     options: ClientOptions;
@@ -227,7 +235,7 @@ declare class ldapActions {
      */
     private wrapPaginatedSearch;
     add(dn: string, entry: AttributesList, req?: Request): Promise<boolean>;
-    modify(dn: string, changes: ModifyRequest, req?: Request): Promise<boolean>;
+    modify(dn: string, changes: ModifyRequest, req?: Request, options?: ModifyOptions): Promise<boolean>;
     rename(dn: string, newRdn: string, req?: Request): Promise<boolean>;
     /**
      * Move an entry to a new location (different parent)

package/dist/src/plugins/auth/openidconnect.d.ts

@@ -5,9 +5,12 @@ import { type Role } from '../../abstract/plugin';
 import { DM } from '../../bin';
 export default class OpenIDConnect extends AuthBase {
     name: string;
+    configApiKey: string;
     roles: Role[];
     /** The library's router, built once: `auth()` returns a fresh one per call. */
     private router?;
+    /** Set once the missing `end_session_endpoint` has been reported. */
+    private warnedNoEndSession;
     constructor(server: DM);
     /**
      * What is handed to `express-openid-connect`.
@@ -19,6 +22,16 @@ export default class OpenIDConnect extends AuthBase {
      */
     buildConfig(): ConfigParams;
     protected identitySource(): string;
+    /**
+     * What `GET /v1/config` publishes under `features`.
+     *
+     * A front-end served by this server cannot tell otherwise that a session
+     * can be ended here: the logout route is this plugin's, and exists only
+     * when it is loaded.
+     *
+     * @returns the logout route, relative to the server root
+     */
+    getConfigApiData(): Record<string, unknown>;
     /**
      * Paths this authentication claims.
      *
@@ -71,4 +84,15 @@ export default class OpenIDConnect extends AuthBase {
      * @param next called once the request carries an identity
      */
     authMethod(req: DmRequest, res: Response, next: () => void): void;
+    /**
+     * Whether `/logout` failed because the provider offers no RP-Initiated
+     * Logout, rather than for a reason worth a 500.
+     *
+     * Warned once: the provider's discovery document does not change while
+     * the server runs.
+     *
+     * @param err what the library handed back
+     * @returns true when the provider has no `end_session_endpoint`
+     */
+    private noEndSession;
 }

package/dist/src/plugins/scim/mapping.d.ts

@@ -104,7 +104,10 @@ export declare function setLockConfigWarn(sink: (message: string) => void): (mes
  * told apart from a deliberate local schema, so they are warned about: what
  * the directory does with a value is beyond anything this can check.
  */
-export declare function resolveLockConfig(attribute: string, value: string): {
+export declare function resolveLockConfig(attribute: string, value: string, options?: {
+    attribute: string;
+    value: string;
+}): {
     attribute: string;
     value: string;
 };

package/dist/src/plugins/scim/patch.d.ts

@@ -44,6 +44,13 @@ export interface PatchContext {
     current: AttributesList;
 }
 export declare function patchToModifyRequest(patch: PatchRequest, ctx: PatchContext): Promise<ModifyRequest>;
+/**
+ * Write a PATCH, read and computed anew by `attempt` each time. A delete
+ * only names values the read showed, so noSuchAttribute means a concurrent
+ * write removed one of them: the PATCH is played once more on a fresh read,
+ * then refused with 409.
+ */
+export declare function writePatch(dn: string, attempt: () => Promise<void>): Promise<void>;
 /**
  * Apply PATCH to a SCIM resource object in-memory (used for PUT-equivalent
  * or when the resource handler prefers object-level manipulation before

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

@@ -0,0 +1,88 @@
+/**
+ * @module plugins/twake/instances
+ *
+ * Gives every account this server creates its workplace instance, once its
+ * entry is written, from the Cloudery or from the cozy-stack admin API. The
+ * address is written once the instance exists, then `user.created` is
+ * published and the entry marked. The event is sent at least once.
+ *
+ * See `docs/usage/plugins/integrations/instances.md`.
+ */
+import type { Express, Request } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
+import { type InstanceProvider, type InstanceRequest } from '../../lib/instanceProviders';
+import type { AttributesList } from '../../lib/ldapActions';
+export interface WorkplaceCreated {
+    twakeId?: string;
+    internalEmail?: string;
+    workplaceFqdn?: string;
+}
+/** An account's instance request, and the id `user.created` names it by. */
+interface Account extends InstanceRequest {
+    twakeId: string;
+}
+export default class TwakeInstances extends DmPlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        rabbitmq: string;
+    };
+    protected readonly patterns: RegExp[];
+    protected readonly provider: InstanceProvider;
+    protected readonly fqdnAttribute: string;
+    protected readonly sentAttribute: string;
+    private readonly locale;
+    private readonly lifecycle;
+    /** Work on one account, or organization, waits for the work before it */
+    private readonly queues;
+    constructor(server: DM);
+    hooks: Hooks;
+    /**
+     * Without a broker `user.created` could not be sent, and with the Cloudery
+     * no address would ever arrive: the server does not start.
+     */
+    api(app: Express): Promise<void>;
+    /**
+     * Make sure this account has its instance: covers a refused or lost
+     * creation, and a `workplace.created` that never arrived. With a request,
+     * the account is read and written with the caller's rights.
+     */
+    ensureInstance(dn: string, req?: Request): Promise<'ready' | 'pending'>;
+    /**
+     * Ask for an organization's own instance, which the Cloudery also needs as
+     * an organization. `organization.created` follows once it exists. For the
+     * application that creates organizations to call.
+     */
+    ensureOrganization(org: {
+        id: string;
+        name: string;
+        domain: string;
+    }): Promise<'ready' | 'pending'>;
+    onWorkplaceCreated(message: WorkplaceCreated): Promise<void>;
+    /** 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;
+    /**
+     * Run `work` once the work already queued for `key` is over. One replica
+     * only: across replicas, `user.created` may still be sent twice.
+     */
+    private serialized;
+    private get organizationId();
+    private get organizationDomain();
+    private get organizationFqdn();
+    private organizationMail;
+    private isOrganization;
+    private findOrganization;
+    private read;
+    protected announce(exchange: string, key: string, message: Record<string, unknown>): Promise<void>;
+    /** What to ask for this account, when it gets an instance at all. */
+    protected account(dn: string, entry: AttributesList): Account | undefined;
+    private match;
+    private id;
+    protected value(entry: AttributesList, attribute: string): unknown;
+    protected findByMail(email: string, req?: Request): Promise<AttributesList | undefined>;
+}
+export {};

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

@@ -0,0 +1,29 @@
+/**
+ * @module plugins/twake/lifecycleAttributes
+ *
+ * The attributes that carry an account's lifecycle (its role, its lock, its
+ * deletion), read from the `--twake-lifecycle-*` options: the ones
+ * `core/twake/lifecycleEvents` reads, and `core/twake/tombstone` writes.
+ */
+import type { Config } from '../../bin';
+import type { AttributesList, AttributeValue } from '../../lib/ldapActions';
+export type DeletedAtFormat = 'iso8601' | 'generalizedTime';
+export interface LifecycleAttributes {
+    role: string;
+    lock: string;
+    lockValue: string;
+    deleted: string;
+    deletedValue: string;
+    deletedAt: string;
+    deletedAtFormat: DeletedAtFormat;
+    reason: string;
+}
+export declare function lifecycleAttributes(config: Config): LifecycleAttributes;
+/** An attribute of an entry, whatever case the caller spelled its name in. */
+export declare function valueOf<T>(entry: Record<string, T>, attribute: string): T | undefined;
+export declare function first(value: AttributeValue | null | undefined): string | undefined;
+export declare const isTombstone: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
+export declare const isLocked: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
+export declare function formatDeletedAt(date: Date, format: DeletedAtFormat): string;
+/** A deletion date as the directory holds it, or undefined if unreadable. */
+export declare function parseDeletedAt(value: string, format: DeletedAtFormat): Date | undefined;

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

@@ -0,0 +1,45 @@
+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 type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number];
+type Payload = Record<string, string>;
+interface Target {
+    exchange: string;
+    routingKey: string;
+    payload: Payload;
+    when: Payload;
+}
+interface Rule {
+    dn: RegExp;
+    targets: Partial<Record<LifecycleEvent, Target[]>>;
+}
+export declare function parseRules(source: string): Rule[];
+export default class TwakeLifecycleEvents extends DmPlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        onLdapChange: string;
+        rabbitmq: string;
+    };
+    private readonly rules;
+    private readonly attrs;
+    constructor(server: DM);
+    /**
+     * core/rabbitmq connects lazily and hands back no client when it cannot:
+     * every event would then be lost, so the server does not start.
+     */
+    assertComposition(): Promise<void>;
+    /**
+     * SCIM deactivates by writing its own lock: on another attribute or
+     * value, `disabled` and `enabled` never follow a SCIM `active` change.
+     */
+    afterLoad(): void;
+    hooks: Hooks;
+    private replay;
+    private match;
+    private onEntryChange;
+    private resolve;
+    private publish;
+}
+export {};

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

@@ -0,0 +1,86 @@
+/**
+ * @module plugins/twake/tombstone
+ *
+ * Turns the delete of an account into a tombstone: the entry stays, flagged
+ * as deleted, dated, locked, with the reason and without the attributes the
+ * deployment wants gone. The address it holds cannot be taken again until the
+ * tombstone is erased.
+ *
+ * SCIM treats a tombstone as gone. Erasing removes the entry and its group
+ * memberships, once the deletion is old enough or when forced, and announces
+ * nothing: the deletion already did.
+ *
+ * See `docs/usage/plugins/integrations/tombstone.md`.
+ */
+import type { Express, Request } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
+export default class TwakeTombstone extends DmPlugin {
+    name: string;
+    roles: Role[];
+    private readonly attrs;
+    private readonly patterns;
+    private readonly defaultReason;
+    private readonly reasonHeader;
+    private readonly reasons;
+    private readonly clearAttributes;
+    private readonly eraseMinAge;
+    private readonly groupBases;
+    private readonly scimPrefix;
+    /** Deletes asked for through {@link tombstone}, with their reason. */
+    private readonly reasonFor;
+    /** Entries being erased: their delete must reach the directory. */
+    private readonly erasing;
+    constructor(server: DM);
+    /**
+     * Last in the delete and add chains: a plugin that may refuse the request
+     * judges it before a tombstone is written or erased.
+     */
+    afterLoad(): void;
+    hooks: Hooks;
+    api(app: Express): void;
+    /**
+     * Delete an entry as a tombstone recording this reason. Goes through the
+     * directory's delete, so every plugin judging deletes judges this one.
+     */
+    tombstone(dn: string, reason: string, req?: Request): Promise<void>;
+    /**
+     * Remove a tombstone and its group memberships. Refused while the deletion
+     * is younger than the configured age, unless forced.
+     */
+    erase(dn: string, { force, req }?: {
+        force?: boolean;
+        req?: Request;
+    }): Promise<void>;
+    /**
+     * 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
+     * would move the tombstone instead of removing it.
+     */
+    assertComposition(): void;
+    /**
+     * Erase a tombstone so a SCIM create can take its identity. The directory
+     * may still refuse the add; the tombstone and its memberships are then put
+     * back once the response is sent.
+     */
+    private replace;
+    /**
+     * Put back a tombstone the add did not replace, with its memberships. A
+     * group the erase left holding only the placeholder loses it again.
+     */
+    private restore;
+    private matches;
+    private isScim;
+    private checkReason;
+    private reasonOf;
+    private read;
+    private writeTombstone;
+    private groupsOf;
+    private leaveGroups;
+    /**
+     * core/ldap/groups and refint clean the same memberships once the delete
+     * lands, so each outcome of a race with them counts as done.
+     */
+    private leaveGroup;
+}

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

@@ -244,6 +244,8 @@ curl -H "Accept: application/json" \
 - `features.ldapFlatGeneric.flatResources`: Array of flat LDAP resources (users, positions, etc.)
 - `features.ldapGroups`: Group management configuration (if enabled)
 - `features.ldapOrganizations`: Organization tree configuration (if enabled)
+- `features.openidconnect.endpoints.logout`: the logout route, when OpenID Connect
+  guards the server ([details](../../usage/plugins/auth/oidc.md#logout))
 
 ---
 

package/docs/plugin-development/hooks.md

@@ -13,10 +13,34 @@ Typescript definitions into [hooks.ts](./src/hooks.ts)
 - **ldapopts**: called before any ldapsearch to modify search options
 - **ldapsearchresult**: called after any ldapsearch to modify search result
 - **ldapaddrequest**: called before any ldapadd
+- **ldapadddone**: launched once an ldapadd has written the entry, not awaited
+- **ldapaddafter**: awaited once an ldapadd has written the entry, before it
+  answers, see [below](#ldapaddafter)
 - **ldapmodifyrequest**: called before any ldapmodify
 - **ldapdeleterequest**: called before any ldapdelete
 - **ldaprenamerequest**: called before any ldap rename/modifyDN operation
 
+### ldapaddafter
+
+For what must follow an add within the same request, such as provisioning
+the account the entry describes.
+
+- Subscribers get `[dn, entry]` and the change context, as `ldapadddone`
+  does. They run one after the other, and `add()` answers once the last has
+  returned.
+- An error is logged and goes no further: the add has succeeded, and the
+  next subscriber still runs. A subscriber that can fail owns its repair
+  path, and should be safe to run again on the same entry.
+- It fires for every add, including those made without a request (trash,
+  storage, appAccountsConsistency, externalUsersInGroups), whose context is
+  empty. Some of these follow an API call all the same, so select entries by
+  their DN or attributes rather than by an empty context.
+- The entry is the one submitted, after `ldapaddrequest`, not what the
+  directory holds: no operational attributes, and the password as given.
+- `ldapadddone` and `onLdapEntryChange` fire whatever this hook does, and in
+  no set order with it: an add event may or may not include what a
+  subscriber here wrote.
+
 ## [onChange](../usage/plugins/ldap/on-change.md) hooks
 
 - **onLdapEntryChange**: called after any write, with the entry before and

package/docs/usage/configuration.md

@@ -445,6 +445,81 @@ Automatically creates/updates/deletes applicative account entries when users are
 
 **Requires:** `core/ldap/onChange`
 
+#### `core/twake/lifecycleEvents`
+
+| CLI                                      | Env                                       | Default                      | Description                                                                                                      |
+| ---------------------------------------- | ----------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--twake-lifecycle-role-attribute`       | `DM_TWAKE_LIFECYCLE_ROLE_ATTRIBUTE`       |                              | Role attribute                                                                                                   |
+| `--twake-lifecycle-lock-attribute`       | `DM_TWAKE_LIFECYCLE_LOCK_ATTRIBUTE`       | `--scim-user-lock-attribute` | Lock attribute                                                                                                   |
+| `--twake-lifecycle-lock-value`           | `DM_TWAKE_LIFECYCLE_LOCK_VALUE`           | see description              | Value marking an account locked: SCIM's with SCIM's attribute, required with another than `pwdAccountLockedTime` |
+| `--twake-lifecycle-deleted-attribute`    | `DM_TWAKE_LIFECYCLE_DELETED_ATTRIBUTE`    |                              | Attribute marking a tombstone                                                                                    |
+| `--twake-lifecycle-deleted-value`        | `DM_TWAKE_LIFECYCLE_DELETED_VALUE`        | `TRUE`                       | Value marking a tombstone                                                                                        |
+| `--twake-lifecycle-deleted-at-attribute` | `DM_TWAKE_LIFECYCLE_DELETED_AT_ATTRIBUTE` |                              | Deletion date attribute                                                                                          |
+| `--twake-lifecycle-deleted-at-format`    | `DM_TWAKE_LIFECYCLE_DELETED_AT_FORMAT`    | `iso8601`                    | `iso8601` or `generalizedTime`                                                                                   |
+| `--twake-lifecycle-rules`                | `DM_TWAKE_LIFECYCLE_RULES`                |                              | Rules: a JSON file, or the JSON itself                                                                           |
+
+See [lifecycle events](plugins/integrations/lifecycle-events.md).
+
+**Requires:** `core/ldap/onChange`, `core/rabbitmq`
+
+#### `core/twake/instances`
+
+| CLI                                              | Env                                               | Default                               | Description                                               |
+| ------------------------------------------------ | ------------------------------------------------- | ------------------------------------- | --------------------------------------------------------- |
+| `--twake-instance-dn`                            | `DM_TWAKE_INSTANCE_DN`                            | `[]`                                  | DN expressions of the accounts to equip                   |
+| `--twake-instance-skip-attribute`                | `DM_TWAKE_INSTANCE_SKIP_ATTRIBUTE`                |                                       | Attribute marking an account with no instance             |
+| `--twake-instance-skip-value`                    | `DM_TWAKE_INSTANCE_SKIP_VALUE`                    |                                       | Its value                                                 |
+| `--twake-instance-provider`                      | `DM_TWAKE_INSTANCE_PROVIDER`                      | `cloudery`                            | `cloudery` or `cozy-stack`                                |
+| `--twake-instance-id`                            | `DM_TWAKE_INSTANCE_ID`                            | `{uid}`                               | Instance id template                                      |
+| `--twake-instance-fqdn-attribute`                | `DM_TWAKE_INSTANCE_FQDN_ATTRIBUTE`                | `twakeWorkspaceUrl`                   | Address attribute                                         |
+| `--twake-instance-sent-attribute`                | `DM_TWAKE_INSTANCE_SENT_ATTRIBUTE`                | `twakeCreatedEventAt`                 | Date the creation event was sent                          |
+| `--twake-instance-locale`                        | `DM_TWAKE_INSTANCE_LOCALE`                        | `en`, `fr` with cozy-stack            | Locale when the entry has none                            |
+| `--twake-instance-timeout`                       | `DM_TWAKE_INSTANCE_TIMEOUT`                       | `30000`                               | Milliseconds a provider call may take                     |
+| `--twake-instance-cloudery-url`                  | `DM_TWAKE_INSTANCE_CLOUDERY_URL`                  |                                       | Cloudery API                                              |
+| `--twake-instance-cloudery-token`                | `DM_TWAKE_INSTANCE_CLOUDERY_TOKEN`                |                                       | Its token                                                 |
+| `--twake-instance-cloudery-domain`               | `DM_TWAKE_INSTANCE_CLOUDERY_DOMAIN`               |                                       | Domain of the instances                                   |
+| `--twake-instance-cloudery-offer`                | `DM_TWAKE_INSTANCE_CLOUDERY_OFFER`                | `b2b_twake_default`                   | Offer of an account's instance                            |
+| `--twake-instance-cloudery-organization-offer`   | `DM_TWAKE_INSTANCE_CLOUDERY_ORGANIZATION_OFFER`   |                                       | Offer of an organization's instance                       |
+| `--twake-instance-cozy-url`                      | `DM_TWAKE_INSTANCE_COZY_URL`                      |                                       | cozy-stack admin API                                      |
+| `--twake-instance-cozy-user`                     | `DM_TWAKE_INSTANCE_COZY_USER`                     | `admin`                               | Its user                                                  |
+| `--twake-instance-cozy-passphrase`               | `DM_TWAKE_INSTANCE_COZY_PASSPHRASE`               |                                       | Its passphrase                                            |
+| `--twake-instance-cozy-domain`                   | `DM_TWAKE_INSTANCE_COZY_DOMAIN`                   |                                       | Domain of the instances                                   |
+| `--twake-instance-cozy-context`                  | `DM_TWAKE_INSTANCE_COZY_CONTEXT`                  | `default`                             | cozy-stack context                                        |
+| `--twake-instance-cozy-apps`                     | `DM_TWAKE_INSTANCE_COZY_APPS`                     | `home,drive,settings,notes,dataproxy` | Apps installed on a new instance                          |
+| `--twake-instance-cozy-org-id`                   | `DM_TWAKE_INSTANCE_COZY_ORG_ID`                   |                                       | Organization id when the DN gives none                    |
+| `--twake-instance-cozy-org-domain`               | `DM_TWAKE_INSTANCE_COZY_ORG_DOMAIN`               |                                       | Organization domain when the DN gives none                |
+| `--twake-instance-auth-exchange`                 | `DM_TWAKE_INSTANCE_AUTH_EXCHANGE`                 | `auth`                                | Exchange of account events                                |
+| `--twake-instance-b2b-exchange`                  | `DM_TWAKE_INSTANCE_B2B_EXCHANGE`                  | `b2b`                                 | Exchange of organization events                           |
+| `--twake-instance-user-created-key`              | `DM_TWAKE_INSTANCE_USER_CREATED_KEY`              | `user.created`                        | Routing key of an account's creation                      |
+| `--twake-instance-organization-created-key`      | `DM_TWAKE_INSTANCE_ORGANIZATION_CREATED_KEY`      | `organization.created`                | Routing key of an organization's creation                 |
+| `--twake-instance-workplace-created-key`         | `DM_TWAKE_INSTANCE_WORKPLACE_CREATED_KEY`         | `workplace.created`                   | Routing key the Cloudery announces on                     |
+| `--twake-instance-queue`                         | `DM_TWAKE_INSTANCE_QUEUE`                         | `workplace.created.ldap-rest`         | Queue shared by the replicas                              |
+| `--twake-instance-organization-base`             | `DM_TWAKE_INSTANCE_ORGANIZATION_BASE`             |                                       | Branch of the organization entries                        |
+| `--twake-instance-organization-id-attribute`     | `DM_TWAKE_INSTANCE_ORGANIZATION_ID_ATTRIBUTE`     | `ou`                                  | Attribute holding an organization's id                    |
+| `--twake-instance-organization-domain-attribute` | `DM_TWAKE_INSTANCE_ORGANIZATION_DOMAIN_ATTRIBUTE` | `twakeDomain`                         | Attribute holding an organization's domain                |
+| `--twake-instance-organization-fqdn-attribute`   | `DM_TWAKE_INSTANCE_ORGANIZATION_FQDN_ATTRIBUTE`   |                                       | Address attribute of an organization (empty: not written) |
+
+See [instances](plugins/integrations/instances.md).
+
+**Requires:** `core/rabbitmq`
+
+#### `core/twake/tombstone`
+
+Reads the `--twake-lifecycle-*` attributes above, and:
+
+| CLI                                  | Env                                   | Default             | Description                               |
+| ------------------------------------ | ------------------------------------- | ------------------- | ----------------------------------------- |
+| `--twake-lifecycle-reason-attribute` | `DM_TWAKE_LIFECYCLE_REASON_ATTRIBUTE` |                     | Deletion reason attribute                 |
+| `--twake-tombstone-dn`               | `DM_TWAKE_TOMBSTONE_DN`               | `[]`                | DN patterns of entries kept as tombstones |
+| `--twake-tombstone-default-reason`   | `DM_TWAKE_TOMBSTONE_DEFAULT_REASON`   | `deleted`           | Reason when none is given                 |
+| `--twake-tombstone-reason-header`    | `DM_TWAKE_TOMBSTONE_REASON_HEADER`    | `x-deletion-reason` | Request header carrying the reason        |
+| `--twake-tombstone-reasons`          | `DM_TWAKE_TOMBSTONE_REASONS`          | `[]`                | Accepted reasons (empty: any)             |
+| `--twake-tombstone-clear-attributes` | `DM_TWAKE_TOMBSTONE_CLEAR_ATTRIBUTES` | `[]`                | Attributes removed from a tombstone       |
+| `--twake-tombstone-erase-min-age`    | `DM_TWAKE_TOMBSTONE_ERASE_MIN_AGE`    | `2592000`           | Seconds before a tombstone may be erased  |
+| `--twake-tombstone-group-bases`      | `DM_TWAKE_TOMBSTONE_GROUP_BASES`      | `--ldap-group-base` | Where memberships are removed at erase    |
+
+See [tombstone](plugins/integrations/tombstone.md).
+
 ### Utility Plugins
 
 #### `core/static`