ldap-rest 0.6.2 → 0.8.0

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

@@ -1,7 +1,22 @@
 import type { AttributesList } from '../../lib/ldapActions';
 import { type ScimUser, type ScimGroup, type ResourceMapping, type MultiValued } from './types';
 export declare const DEFAULT_USER_MAPPING: ResourceMapping;
+/**
+ * Group mapping.
+ *
+ * `externalId` is deliberately absent: RFC 7643 section 3.1 defines it as the
+ * *provisioning client's* identifier, so it cannot be served from a
+ * server-assigned value. groupOfNames has no attribute meant to hold one
+ * either, so the deployment names one with
+ * `--scim-group-external-id-attribute` and the entry is added at runtime by
+ * `withExternalId()`.
+ */
 export declare const DEFAULT_GROUP_MAPPING: ResourceMapping;
+/**
+ * Add the `externalId` entry when the deployment named an attribute to store
+ * it in. An entry already present — from a mapping override — wins.
+ */
+export declare function withExternalId(mapping: ResourceMapping, ldapAttribute: string): ResourceMapping;
 /**
  * LDAP GeneralizedTime (RFC 4517 §3.3.13) → SCIM DateTime (RFC 7643 §2.3.5,
  * an `xsd:dateTime`).
@@ -31,7 +46,81 @@ export interface MappingContext {
     resourceType: 'User' | 'Group';
     baseUrl?: string;
     scimPrefix: string;
+    /**
+     * LDAP attribute whose *presence* marks the account as locked, and the
+     * value written to lock it. Both come from `resolveLockConfig()`, which is
+     * the only place the defaults live: re-defaulting here would let a context
+     * built outside the plugin reach the directory with a pair the startup
+     * guard never saw. Groups have no `active`, so they pass empty strings.
+     */
+    lockAttribute: string;
+    lockValue: string;
 }
+/**
+ * SCIM `active` (RFC 7643 section 4.1.1) has no direct LDAP equivalent. We
+ * model it on the presence of one attribute: present means locked, absent
+ * means active.
+ *
+ * The default is the ppolicy overlay's `pwdAccountLockedTime`, whose
+ * conventional "locked forever" value is a GeneralizedTime in the distant
+ * past. A directory without that overlay points
+ * `--scim-user-lock-attribute` / `--scim-user-lock-value` somewhere else
+ * (`nsAccountLock` / `TRUE`, for instance).
+ */
+export declare const DEFAULT_LOCK_ATTRIBUTE = "pwdAccountLockedTime";
+export declare const DEFAULT_LOCK_VALUE = "000001010000Z";
+/**
+ * Where the configuration warnings go. A seam rather than a direct
+ * `console.warn` so the unit tests can read what was said instead of
+ * asserting on stderr.
+ */
+export declare let warn: (message: string) => void;
+/** Testing seam: replace the warning sink, and get the previous one back. */
+export declare function setLockConfigWarn(sink: (message: string) => void): (message: string) => void;
+/**
+ * Settle the lock configuration, or refuse to start.
+ *
+ * Ways to get a deployment that answers 200 to every deactivation while the
+ * directory locks nothing:
+ *
+ * - naming an attribute without its value. `000001010000Z` is the ppolicy
+ *   convention and means nothing to `nsAccountLock`, which 389-ds reads as
+ *   locked only when it says `true` — so every deactivation would be
+ *   written, read back as `active: false`, and the account would keep
+ *   binding.
+ * - naming an attribute and pinning that same ppolicy value on it, which a
+ *   deployment template that always sets both flags does by default. The
+ *   guard above sees a value and passes; the outcome is identical.
+ * - the mirror: a value the default attribute cannot hold.
+ *   `pwdAccountLockedTime` is a GeneralizedTime, so `TRUE` is refused by the
+ *   directory's schema — or, where the attribute was redefined locally,
+ *   stored and ignored.
+ * - a name that is not an attribute description. It is interpolated into the
+ *   emitted LDAP filter for `active eq …`, where a metacharacter makes
+ *   every list either malformed or quietly wrong.
+ *
+ * All are operator mistakes rather than attacks, and all are silent. The
+ * first and the last are refused outright. The two in the middle cannot be
+ * 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): {
+    attribute: string;
+    value: string;
+};
+/**
+ * Read a SCIM `active` value, wherever it came from.
+ *
+ * `undefined` means the body did not mention it — which is not the same as
+ * `true`. Only a boolean, or the two canonical strings some providers send
+ * instead, are accepted: guessing at `"0"`, `null` or `1` would let a
+ * deprovisioning request be executed as a re-activation, and answer 200
+ * doing it. The one rule lives here so POST, PUT, PATCH and the filter
+ * translator cannot drift apart.
+ */
+export declare function readActive(value: unknown): boolean | undefined;
+/** Is this entry locked, per the configured lock attribute? */
+export declare function isLocked(entry: AttributesList, ctx: MappingContext): boolean;
 /** Resolve the SCIM id for an LDAP entry, per configuration. */
 export declare function resolveScimId(entry: AttributesList, ctx: MappingContext): string | undefined;
 export declare function buildLocation(id: string, ctx: MappingContext): string | undefined;
@@ -44,6 +133,7 @@ export declare function ldapToScimUser(entry: AttributesList, mapping: ResourceM
 export declare function scimUserToLdap(user: ScimUser, mapping: ResourceMapping, ctx: MappingContext, objectClass: string[]): {
     rdn: string;
     attributes: AttributesList;
+    active?: boolean;
 };
 export declare function ldapToScimGroup(entry: AttributesList, mapping: ResourceMapping, ctx: MappingContext, memberResolver?: (dn: string) => MultiValued | undefined): ScimGroup;
 /**
@@ -58,15 +148,6 @@ export declare function scimGroupToLdap(group: ScimGroup, mapping: ResourceMappi
  * List of LDAP attributes to request from the directory so all
  * mapped SCIM attributes can be populated.
  */
-/**
- * The ppolicy overlay's lock marker, whose presence means `active: false`.
- *
- * Operational, so a search that does not name it never answers it: the read
- * path has to ask for it explicitly.
- */
-export declare const LOCK_ATTRIBUTE = "pwdAccountLockedTime";
-/** Is this entry locked, per the ppolicy lock marker? */
-export declare function isLocked(entry: AttributesList): boolean;
 export declare function requiredLdapAttributes(mapping: ResourceMapping, extra?: string[]): string[];
 /**
  * Given a SCIM attribute path like "emails.value" or "name.familyName",

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

@@ -19,7 +19,7 @@
  * member operations for Groups are handled via the caller-provided
  * `resolveMemberRef` hook (SCIM id → LDAP DN lookup).
  */
-import type { ModifyRequest } from '../../lib/ldapActions';
+import type { AttributesList, ModifyRequest } from '../../lib/ldapActions';
 import { type ResourceMapping, type PatchRequest } from './types';
 export interface PatchContext {
     mapping: ResourceMapping;
@@ -27,6 +27,21 @@ export interface PatchContext {
     resolveMemberRef?: (value: string) => Promise<string | undefined>;
     /** The LDAP attribute holding members, default 'member'. */
     memberAttribute?: string;
+    /**
+     * For Users: the attribute whose presence marks the account as locked, and
+     * the value to write when SCIM `active` is set to false.
+     */
+    lockAttribute?: string;
+    lockValue?: string;
+    /** True when this resource type carries SCIM `active` (Users only). */
+    supportsActive?: boolean;
+    /**
+     * The entry as it stands. RFC 7644 section 3.5.2 applies operations in
+     * order, so they are played against this and only the resulting difference
+     * is sent — without it, two operations touching one attribute would
+     * collapse into whichever the emitter happened to keep.
+     */
+    current: AttributesList;
 }
 export declare function patchToModifyRequest(patch: PatchRequest, ctx: PatchContext): Promise<ModifyRequest>;
 /**

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

@@ -0,0 +1,15 @@
+export interface ProjectionQuery {
+    attributes?: string[];
+    excludedAttributes?: string[];
+}
+/**
+ * Raise when both parameters are given: RFC 7644 §3.9 makes them mutually
+ * exclusive, and honouring one silently would hide the mistake.
+ */
+export declare function assertProjection(query: ProjectionQuery): void;
+/** Apply `attributes` / `excludedAttributes` to one resource. */
+export declare function projectResource<T extends Record<string, unknown>>(resource: T, query: ProjectionQuery): T;
+/** Apply the projection to every resource of a ListResponse. */
+export declare function projectList<T extends Record<string, unknown>, L extends {
+    Resources: T[];
+}>(list: L, query: ProjectionQuery): L;

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

@@ -419,6 +419,11 @@ export default class Scim extends DmPlugin {
      * `--scim-base-url` to make it absolute and trustworthy too.
      */
     private scimResource;
+    /**
+     * `attributes` / `excludedAttributes` (RFC 7644 section 3.9). Accepted on
+     * every route that answers a resource, not only the list ones.
+     */
+    private parseProjection;
     private readScimBody;
     api(app: Express): void;
     private parseListQuery;

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

@@ -41,14 +41,35 @@ export declare class ScimUsers {
     private readonly maxResults;
     private readonly maxScanned;
     private readonly scimPrefix;
+    private readonly lockAttribute;
+    private readonly lockValue;
     constructor(opts: ScimUsersOptions);
     private ctx;
+    /**
+     * LDAP attributes to fetch. The lock attribute backing SCIM `active` is
+     * operational on most directories, so it is never returned unless asked
+     * for by name.
+     */
+    private ldapAttributes;
     private dnForId;
     get(req: DmRequest, id: string): Promise<ScimUser>;
     list(req: DmRequest, query: ListQuery): Promise<ListResponse<ScimUser>>;
     create(req: DmRequest, resource: ScimUser): Promise<ScimUser>;
     replace(req: DmRequest, id: string, resource: ScimUser): Promise<ScimUser>;
     patch(req: DmRequest, id: string, patch: PatchRequest): Promise<ScimUser>;
+    /**
+     * Re-raise a directory refusal that names the schema, pointing at the flag
+     * that caused it.
+     *
+     * The generic translation in `errors` cannot do this: it sees the error,
+     * not the configuration. Only this class knows which attribute was
+     * configured to back `active`, and the shipped default —
+     * `pwdAccountLockedTime` — exists only where slapd loads the ppolicy
+     * overlay, which is the common way to meet this.
+     */
+    private lockSchemaError;
+    /** Fetch the raw LDAP entry backing a SCIM id, or raise 404. */
+    private currentEntry;
     delete(req: DmRequest, id: string): Promise<void>;
     /**
      * Given a SCIM member value (typically an id), return the LDAP DN.

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

@@ -0,0 +1,113 @@
+import TwakePlugin from '../../abstract/twakePlugin';
+import { type Role } from '../../abstract/plugin';
+import { Hooks } from '../../hooks';
+/**
+ * Plugin to sync LDAP resources and users with Twake Calendar
+ *
+ * Monitors a LDAP branch for resources (meeting rooms, equipment, etc.)
+ * and automatically creates/updates/deletes them in Twake Calendar via WebAdmin API.
+ *
+ * Also propagates user identity changes (email, first name, last name) to the
+ * Twake Calendar "registered users" via the WebAdmin API.
+ */
+export default class Calendar extends TwakePlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        onLdapChange: string;
+    };
+    private resourceBase;
+    private resourceObjectClass;
+    private resourceCreator;
+    private resourceDomain;
+    private firstnameAttr;
+    private lastnameAttr;
+    constructor(server: import('../../bin').DM);
+    hooks: Hooks;
+    /**
+     * Check if a LDAP entry is a calendar resource
+     */
+    private isResource;
+    /**
+     * Whether a DN is the configured resource branch or sits below it.
+     *
+     * Compared RDN by RDN ({@link isDnInBranch}), not as text: a substring test
+     * took `cn=Salle,ou=resourcesArchive,…` for a resource when the branch was
+     * given as `ou=resources`, and missed a DN written `cn=Salle, ou=resources,
+     * …` — the spaces a client puts after its commas are not part of the DN.
+     *
+     * No configured branch means no branch restriction, as before.
+     */
+    private isInResourceBranch;
+    /**
+     * URL of one resource in the WebAdmin API.
+     *
+     * The id is a raw RDN value, so it can carry anything a directory accepts:
+     * `cn=Salle A/B` interpolated as such builds `/resources/Salle A/B`, a path
+     * naming another resource or none. Percent-encoding keeps it one segment.
+     */
+    private resourceUrl;
+    /**
+     * Build resource data for Calendar API from LDAP attributes
+     */
+    private buildResourceData;
+    /**
+     * The name a resource is known by in Calendar: the value of the entry's own
+     * RDN, escapes removed.
+     *
+     * Taken from the first RDN, whatever its attribute type, so that an entity
+     * whose mainAttribute is neither `cn` nor `uid` gets an id of its own. The
+     * previous derivation looked for `cn=`/`uid=` anywhere in the DN, so
+     * `o=Room 12,cn=zone,ou=resources,…` answered `zone`, its parent's id — a
+     * modify on that entry then patched another resource. It also cut the value
+     * at the first comma, escaped or not, so `cn=Salle\, 2` answered `Salle\`,
+     * an id two rooms could share.
+     *
+     * A DN with `cn=` or `uid=` as its own first RDN and no escape in its value
+     * — the shape a deployment has — answers exactly what it answered before.
+     */
+    private getResourceId;
+    /**
+     * Find a Calendar registered user by email.
+     *
+     * `GET /registeredUsers?email=…` answers the one user, or 404. Calendar
+     * lower-cases the address before matching it (James's `Username` folds both
+     * parts), which is also how it stores every address, so a case difference
+     * between LDAP and Calendar does not matter. The one record this misses is
+     * a legacy one whose stored address kept upper case, written without going
+     * through `Username`; the full-list lookup used before did find it.
+     *
+     * Calendar releases before 1.0.0.1 ignore the `email` parameter and answer
+     * the full list; the user is then picked from it, case-insensitively.
+     *
+     * @param email Address Calendar holds for the user
+     * @param log Log context of the calling sync
+     * @returns The registered user, or null when it is not registered or the
+     *   lookup failed (both logged)
+     */
+    private findRegisteredUser;
+    /**
+     * Synchronize an LDAP user's identity (email, first and last name) to the
+     * Twake Calendar registered users via the WebAdmin API.
+     *
+     * Registered users are keyed by an internal id: the user is looked up with
+     * `GET /registeredUsers?email=…` (see findRegisteredUser), then
+     * `PATCH /registeredUsers?id={id}` with the LDAP values.
+     *
+     * @param event Hook name, used for logging
+     * @param dn LDAP DN of the user
+     * @param lookupEmail Email used to locate the existing registered user.
+     *   Defaults to the user's current mail; pass the OLD mail when the email
+     *   itself is changing (Calendar still holds the previous address).
+     */
+    syncRegisteredUser(event: string, dn: string, lookupEmail?: string): Promise<void>;
+    /**
+     * Delete user data from Twake Calendar WebAdmin API
+     * Calls POST /users/{mail}?action=deleteData
+     * @param mail - The user's email address
+     * @returns Task information or null on error
+     */
+    deleteUserData(mail: string): Promise<{
+        taskId: string;
+    } | null>;
+}

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

@@ -1,63 +1,14 @@
-import TwakePlugin from '../../abstract/twakePlugin';
-import { type Role } from '../../abstract/plugin';
-import { Hooks } from '../../hooks';
 /**
- * Plugin to sync LDAP resources and users with Twake Calendar
+ * @deprecated Use `core/twake/calendar` instead. This file is a
+ * backwards-compatibility shim for setups that still load the plugin under
+ * its historical name, which undersold it: besides resources, it propagates
+ * user identity changes (email, first and last name) to Twake Calendar. It
+ * will be removed in a future major release.
  *
- * Monitors a LDAP branch for resources (meeting rooms, equipment, etc.)
- * and automatically creates/updates/deletes them in Twake Calendar via WebAdmin API.
- *
- * Also propagates user identity changes (email, first name, last name) to the
- * Twake Calendar "registered users" via the WebAdmin API.
+ * The instance keeps registering as `calendarResources`, so code looking it
+ * up by that name keeps finding it.
  */
-export default class CalendarResources extends TwakePlugin {
+import Calendar from './calendar';
+export default class CalendarResources extends Calendar {
     name: string;
-    roles: Role[];
-    dependencies: {
-        onLdapChange: string;
-    };
-    private resourceBase;
-    private resourceObjectClass;
-    private resourceCreator;
-    private resourceDomain;
-    private firstnameAttr;
-    private lastnameAttr;
-    constructor(server: import('../../bin').DM);
-    hooks: Hooks;
-    /**
-     * Check if a LDAP entry is a calendar resource
-     */
-    private isResource;
-    /**
-     * Build resource data for Calendar API from LDAP attributes
-     */
-    private buildResourceData;
-    /**
-     * Extract resource ID from DN
-     */
-    private getResourceId;
-    /**
-     * Synchronize an LDAP user's identity (email, first and last name) to the
-     * Twake Calendar registered users via the WebAdmin API.
-     *
-     * Registered users are keyed by an internal id, and `GET /registeredUsers`
-     * exposes no filter, so we list all registered users, locate the entry by
-     * email, then `PATCH /registeredUsers?id={id}` with the LDAP values.
-     *
-     * @param event Hook name, used for logging
-     * @param dn LDAP DN of the user
-     * @param lookupEmail Email used to locate the existing registered user.
-     *   Defaults to the user's current mail; pass the OLD mail when the email
-     *   itself is changing (Calendar still holds the previous address).
-     */
-    syncRegisteredUser(event: string, dn: string, lookupEmail?: string): Promise<void>;
-    /**
-     * Delete user data from Twake Calendar WebAdmin API
-     * Calls POST /users/{mail}?action=deleteData
-     * @param mail - The user's email address
-     * @returns Task information or null on error
-     */
-    deleteUserData(mail: string): Promise<{
-        taskId: string;
-    } | null>;
 }

package/docs/README.md

@@ -10,6 +10,8 @@ Installation, configuration and plugin usage.
 
 - **[Getting Started](usage/README.md)** - Quick start guide
 - **[Configuration](usage/configuration.md)** - CLI options and environment variables
+- **[Upgrading](usage/upgrading.md)** - What to check before deploying a new version
+- **[Directory audit](usage/directory-audit.md)** - What a schema would refuse in an existing directory
 - **[Plugins](usage/plugins/README.md)** - Documentation for all available plugins
 
 ### [Plugin Development](plugin-development/README.md)

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

@@ -220,7 +220,7 @@ private pluginTags: Map<string, string> = new Map([
   ['ldapFlatGeneric', 'Entities'],
   ['ldapBulkImport', 'Bulk Import'],
   ['james', 'Apache James Integration'],
-  ['calendarResources', 'Calendar Resources'],
+  ['calendar', 'Twake Calendar'],
   ['configApi', 'Configuration'],
   ['static', 'Static Files'],
 ]);

package/docs/client-development/browser/libraries.md

@@ -34,7 +34,7 @@ This guide covers LDAP-Rest's browser libraries for building LDAP management int
 
 ## Overview
 
-LDAP-Rest provides four ready-to-use browser libraries for building LDAP management interfaces:
+LDAP-Rest provides ready-to-use browser libraries for building LDAP management interfaces:
 
 - **LdapTreeViewer** - Interactive hierarchical tree view of LDAP organizations
 - **LdapUserEditor** - Complete user management interface with organization tree, user list, and edit form

package/docs/plugin-development/README.md

@@ -455,6 +455,28 @@ export default class MyPlugin extends DmPlugin {
 
 The `this.server.ldap` object provides access to all LDAP operations:
 
+> **Serving an HTTP request? Bind it first.**
+>
+> The authorization plugins (`core/auth/authzPerBranch`,
+> `core/auth/authzDynamic`, …) hook `ldapsearchrequest`, `ldapaddrequest`,
+> `ldapmodifyrequest`, `ldaprenamerequest` and `ldapdeleterequest`, and they
+> **skip every check when the request is missing**. The methods below take it as a trailing
+> optional argument, so forgetting it does not fail — it silently authorizes
+> the operation. Three such bugs shipped in the SCIM plugin.
+>
+> In a request handler, bind once and use the result:
+>
+> ```typescript
+> const directory = this.server.ldap.forRequest(req);
+> await directory.search({ scope: 'base' }, dn);
+> await directory.modify(dn, changes);
+> ```
+>
+> `forRequest()` returns a `RequestBoundLdap`, whose methods have no request
+> parameter at all — the omission stops being expressible. Use the unbound
+> methods only for work that genuinely belongs to no request, such as startup
+> or scheduled tasks, where passing nothing is the deliberate answer.
+
 #### Search
 
 ```typescript

package/docs/plugin-development/dependencies.md

@@ -190,15 +190,18 @@ dependencies = {
 - **Consumes Hooks**: (Hooks provided by `onLdapChange`)
 - **Notes**: Synchronizes LDAP users/groups with Apache James mail server
 
-#### `calendarResources` (twake/calendarResources)
+#### `calendar` (twake/calendar)
 
-- **Dependencies**: None
+- **Dependencies**:
+  - `onLdapChange: 'core/ldap/onChange'` ⚠️ **Required**
 - **Provides Hooks**:
   - `ldapcalendarResourceadddone` - After calendar resource added
   - `ldapcalendarResourcemodifydone` - After calendar resource modified
   - `ldapcalendarResourcedeletedone` - After calendar resource deleted
-- **Consumes Hooks**: None
-- **Notes**: Synchronizes calendar resources with Twake Calendar
+  - `onLdapChange` - Propagates user email / name changes
+- **Consumes Hooks**: (Hooks provided by `onLdapChange`)
+- **Notes**: Synchronizes calendar resources and registered users with Twake
+  Calendar. Formerly `calendarResources`, still loadable under that name
 
 #### `appAccountsConsistency` (twake/appAccountsConsistency)
 
@@ -361,7 +364,7 @@ ldapOrganizations (core/ldap/organization)
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                              │
 │  ┌────────────────────────────┐      ┌──────────────────────────┐          │
-│  │        james               │      │  calendarResources       │          │
+│  │        james               │      │  calendar                │          │
 │  │  (Apache James sync)       │      │  (Twake Calendar sync)   │          │
 │  │                            │      │                          │          │
 │  │  Requires:                 │      │                          │          │
@@ -466,7 +469,7 @@ graph TB
 
     %% Twake Integration
     james[james]
-    calendar[calendarResources]
+    calendar[calendar]
 
     %% Utility
     static[static]
@@ -521,7 +524,7 @@ graph TB
 ### 4. Integration Plugins
 
 13. `james` - After `onChange` and `groups`
-14. `calendarResources` - Calendar sync (optional)
+14. `calendar` - Twake Calendar sync (optional)
 
 ### 5. Utility Plugins (can load anytime)
 

package/docs/presentations/en.md

@@ -100,7 +100,7 @@ export default class MyPlugin extends DmPlugin {
 ## Integrations
 
 - **twake/james** - Apache James Synchronization (mail)
-- **twake/calendarResources** - Calendar Resources
+- **twake/calendar** - Twake Calendar resources and users
 
 <!-- end_slide -->
 

package/docs/presentations/fr.md

@@ -100,7 +100,7 @@ export default class MyPlugin extends DmPlugin {
 ## Intégrations
 
 - **twake/james** - Synchronisation Apache James (mail)
-- **twake/calendarResources** - Ressources calendrier
+- **twake/calendar** - Ressources et utilisateurs Twake Calendar
 
 <!-- end_slide -->
 

package/docs/usage/README.md

@@ -86,4 +86,6 @@ The system will:
 
 - **[Configuration](configuration.md)** - CLI options and environment variables
 - **[Plugins](plugins/README.md)** - Choose and configure plugins
+- **[Upgrading](upgrading.md)** - What to check before deploying a new version
+- **[Directory audit](directory-audit.md)** - What a schema would refuse in an existing directory
 - **[Troubleshooting](troubleshooting.md)** - Problem resolution

package/docs/usage/configuration.md

@@ -35,7 +35,7 @@ All LDAP-Rest configuration options.
     - [core/auth/trustedProxy](#coreauthtrustedproxy)
   - [Twake Integration Plugins](#twake-integration-plugins)
     - [core/twake/james](#coretwakejames)
-    - [core/twake/calendarResources](#coretwakecalendarresources)
+    - [core/twake/calendar](#coretwakecalendar)
     - [core/twake/applicativeAccounts](#coretwakeapplicativeaccounts)
     - [core/twake/appAccountsConsistency](#coretwakeappaccountsconsistency)
   - [Utility Plugins](#utility-plugins)
@@ -92,18 +92,34 @@ export DM_PLUGINS="core/auth/token,core/ldap/flatGeneric,core/ldap/groups"
 
 ## LDAP Connection
 
-| CLI                          | Plural           | Env                      | Default                            | Description                |
-| ---------------------------- | ---------------- | ------------------------ | ---------------------------------- | -------------------------- |
-| `--ldap-url`                 | `--ldap-urls`    | `DM_LDAP_URL`            | `ldap://localhost`                 | LDAP server URL(s)         |
-| `--ldap-dn`                  |                  | `DM_LDAP_DN`             | `cn=admin,dc=example,dc=com`       | Bind DN                    |
-| `--ldap-pwd`                 |                  | `DM_LDAP_PWD`            | `admin`                            | Password                   |
-| `--ldap-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches       |
-| `--ldap-user-main-attribute` |                  | `DM_LDAP_USER_ATTRIBUTE` | `uid`                              | User identifier attribute  |
-| `--ldap-cache-max`           |                  | `DM_LDAP_CACHE_MAX`      | `1000`                             | Max cache entries          |
-| `--ldap-cache-ttl`           |                  | `DM_LDAP_CACHE_TTL`      | `300`                              | Cache TTL (seconds)        |
-| `--ldap-pool-size`           |                  | `DM_LDAP_POOL_SIZE`      | `5`                                | Connection pool size       |
-| `--ldap-connection-ttl`      |                  | `DM_LDAP_CONNECTION_TTL` | `60`                               | Connection TTL (seconds)   |
-| `--user-class`               | `--user-classes` | `DM_USER_CLASSES`        | `top,twakeAccount,twakeWhitePages` | Default user objectClasses |
+| CLI                          | Plural           | Env                      | Default                            | Description                                 |
+| ---------------------------- | ---------------- | ------------------------ | ---------------------------------- | ------------------------------------------- |
+| `--ldap-url`                 | `--ldap-urls`    | `DM_LDAP_URL`            | `ldap://localhost`                 | LDAP server URL(s)                          |
+| `--ldap-dn`                  |                  | `DM_LDAP_DN`             | `cn=admin,dc=example,dc=com`       | Bind DN                                     |
+| `--ldap-pwd`                 |                  | `DM_LDAP_PWD`            | `admin`                            | Password                                    |
+| `--ldap-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches                        |
+| `--ldap-user-main-attribute` |                  | `DM_LDAP_USER_ATTRIBUTE` | `uid`                              | User identifier attribute                   |
+| `--ldap-cache-max`           |                  | `DM_LDAP_CACHE_MAX`      | `1000`                             | Max cache entries                           |
+| `--ldap-cache-ttl`           |                  | `DM_LDAP_CACHE_TTL`      | `0`                                | Search cache TTL (seconds), `0` disables it |
+| `--ldap-pool-size`           |                  | `DM_LDAP_POOL_SIZE`      | `5`                                | Connection pool size                        |
+| `--ldap-connection-ttl`      |                  | `DM_LDAP_CONNECTION_TTL` | `60`                               | Connection TTL (seconds)                    |
+| `--user-class`               | `--user-classes` | `DM_USER_CLASSES`        | `top,twakeAccount,twakeWhitePages` | Default user objectClasses                  |
+
+### The search cache
+
+`--ldap-cache-ttl` holds the answers of non-paginated, base-scope searches —
+single-entry lookups by DN — for that many seconds. It is **off by default**:
+until the branch storing a result was repaired, nothing was ever cached, so no
+deployment has run with it on, and a cache that silently serves stale entries
+is not something to switch on for everyone at once.
+
+Writes made through this service (add, modify, rename, move, delete) drop what
+they change, the moved subtree included. Writes made anywhere else do not:
+another replica of this service, an LSC synchronisation, a hand-run
+`ldapmodify`. Each process caches on its own, and only its own writes drop what
+it cached. Turn the cache on when this service is the only writer, or when
+serving an entry up to `--ldap-cache-ttl` seconds old is acceptable; leave it
+at `0` otherwise.
 
 ## Special Attributes
 
@@ -188,7 +204,7 @@ Monitors LDAP modifications and triggers hooks for attribute changes. No configu
 
 #### `core/ldap/departmentSync`
 
-Maintains consistency of department links when organizations are renamed/moved. No configuration options - uses [core/ldap/organizations](#coreldaporganizations) settings.
+Maintains consistency of department links when organizations are renamed/moved: it recomputes the path of the organization and of its sub-organizations (those already holding one), then updates the link and path of the entries linked to any of them. The attributes are those the loaded schemas declare through the `organizationPath` and `organizationLink` roles, then the configured `--ldap-organization-path-attribute` and `--ldap-organization-link-attribute`. No configuration options of its own - uses [core/ldap/organizations](#coreldaporganizations) settings.
 
 #### `core/ldap/raw`
 
@@ -308,7 +324,9 @@ Empty means the plugin guards every path. Scoping several instances to different
 | `--james-mailbox-type-attribute` |                                 | `DM_JAMES_MAILBOX_TYPE_ATTRIBUTE` | `twakeMailboxType`      | Mailbox type attribute      |
 | `--ldap-concurrency`             |                                 | `DM_LDAP_CONCURRENCY`             | `10`                    | LDAP operations concurrency |
 
-#### `core/twake/calendarResources`
+#### `core/twake/calendar`
+
+Formerly `core/twake/calendarResources`, still accepted as a deprecated alias.
 
 | CLI                               | Env                                | Default                 | Description                   |
 | --------------------------------- | ---------------------------------- | ----------------------- | ----------------------------- |
@@ -319,6 +337,8 @@ Empty means the plugin guards every path. Scoping several instances to different
 | `--calendar-resource-objectclass` | `DM_CALENDAR_RESOURCE_OBJECTCLASS` |                         | Resource objectClass          |
 | `--calendar-resource-creator`     | `DM_CALENDAR_RESOURCE_CREATOR`     |                         | Resource creator              |
 | `--calendar-resource-domain`      | `DM_CALENDAR_RESOURCE_DOMAIN`      |                         | Resource domain               |
+| `--calendar-firstname-attribute`  | `DM_CALENDAR_FIRSTNAME_ATTRIBUTE`  | `givenName`             | Registered user first name    |
+| `--calendar-lastname-attribute`   | `DM_CALENDAR_LASTNAME_ATTRIBUTE`   | `sn`                    | Registered user last name     |
 
 #### `core/twake/applicativeAccounts`