ldap-rest 0.7.0 → 0.8.1

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

@@ -11,10 +11,10 @@ Plugins for connecting LDAP-Rest to external systems.
 
 ## Twake
 
-| Plugin                                      | Description                              |
-| ------------------------------------------- | ---------------------------------------- |
-| [calendar-resources](calendar-resources.md) | Calendar resource synchronization        |
-| [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) |
 
 ## Prerequisites
 
@@ -37,6 +37,6 @@ James plugins require:
 core/twake/james
   └─ requires: core/ldap/onChange
 
-core/twake/calendarResources
+core/twake/calendar
   └─ requires: core/ldap/onChange
 ```

package/docs/usage/plugins/integrations/{calendar-resources.md → calendar.md}

@@ -1,6 +1,13 @@
-# Twake Calendar Resources Plugin
+# Twake Calendar Plugin
 
-Plugin to automatically synchronize LDAP resources (meeting rooms, equipment, etc.) with Twake Calendar via its WebAdmin API.
+Plugin to keep Twake Calendar in sync with LDAP via its WebAdmin API:
+
+- resources (meeting rooms, equipment, etc.) stored in an LDAP branch
+- registered users, whose email, first name and last name follow LDAP
+
+> Formerly `core/twake/calendarResources`. That name still loads the plugin,
+> registered as `calendarResources`, but logs a deprecation warning and will
+> be removed in a future major release.
 
 ## Features
 
@@ -8,6 +15,7 @@ Plugin to automatically synchronize LDAP resources (meeting rooms, equipment, et
 - **Automatic Updates**: When a resource is modified in LDAP, changes are synced to Twake Calendar
 - **Automatic Deletion**: When a resource is removed from LDAP, it's deleted from Twake Calendar
 - **Flexible Configuration**: Configure which LDAP branch and objectClass to monitor
+- **User Identity Propagation**: When a user's email, first name or last name changes in LDAP, the matching Calendar registered user is updated
 
 ## Configuration
 
@@ -15,10 +23,15 @@ Plugin to automatically synchronize LDAP resources (meeting rooms, equipment, et
 
 - `DM_CALENDAR_WEBADMIN_URL`: URL of the Twake Calendar WebAdmin API (default: `http://localhost:8080`)
 - `DM_CALENDAR_WEBADMIN_TOKEN`: Bearer token for WebAdmin API authentication
-- `DM_CALENDAR_RESOURCE_BASE`: LDAP branch to monitor for resources (e.g., `ou=resources,dc=example,dc=com`)
-- `DM_CALENDAR_RESOURCE_OBJECTCLASS`: Optional objectClass filter (only process entries with this objectClass)
+- `DM_CALENDAR_RESOURCE_BASE`: LDAP branch to monitor for resources, as a full DN (e.g., `ou=resources,dc=example,dc=com`). It is compared to an entry's DN part by part, so a partial value such as `ou=resources` names no branch and matches nothing (the plugin warns at startup when the value is not a DN of the directory).
+- `DM_CALENDAR_RESOURCE_OBJECTCLASS`: Optional objectClass filter, applied when a resource is **created** (see [Resource identity](#resource-identity))
 - `DM_CALENDAR_RESOURCE_CREATOR`: Default creator email for resources (default: `admin@example.com`)
 - `DM_CALENDAR_RESOURCE_DOMAIN`: Default domain for resources (extracted from DN if not specified)
+- `DM_CALENDAR_FIRSTNAME_ATTRIBUTE`: LDAP attribute holding a user's first name (default: `givenName`)
+- `DM_CALENDAR_LASTNAME_ATTRIBUTE`: LDAP attribute holding a user's last name (default: `sn`)
+
+The resource variables are only needed for resource synchronization; user
+identity propagation only needs the WebAdmin URL and token.
 
 ### Required Dependencies
 
@@ -66,6 +79,49 @@ The plugin uses the following WebAdmin API endpoints:
 - `POST /resources` - Create a new resource
 - `PATCH /resources/{id}` - Update an existing resource
 - `DELETE /resources/{id}` - Delete a resource
+- `GET /registeredUsers?email={mail}` - Find the registered user to update
+- `PATCH /registeredUsers?id={id}` - Update a registered user's email, first and last name
+- `POST /users/{mail}?action=deleteData` - Delete a user's data (see `deleteUserData`)
+
+The resource id goes into the path percent-encoded, so a `/` or a `#` in it
+cannot build a path naming something else. The user's address is left as it is
+written — `user@example.com`, `@` being legal in a path segment — which is what
+`plugins/twake/james` does with the same WebAdmin; whether the two should
+encode it is issue #175.
+
+### Registered Users
+
+A change of the configured mail attribute updates the registered user found by
+its **previous** address; a change of the first or last name attribute updates
+the one found by its current address. In both cases the email, first name and
+last name are re-read from LDAP and sent together. Adding or removing the mail
+attribute, and users not registered in Calendar, are skipped.
+
+Calendar lower-cases the address before looking it up, which is also how it
+stores addresses, so a case difference between LDAP and Calendar does not
+matter. The exception is a legacy record whose stored address kept upper case
+(written without Calendar's normalisation, e.g. migrated data): it is not
+found, and its user is logged as not registered. Calendar releases before
+1.0.0.1 ignore the `email` parameter and answer the full list of registered
+users; the plugin then picks the user from it, which works but costs a full
+listing per change.
+
+### Resource identity
+
+A resource is known to Calendar by an `id`, which is the value of its LDAP
+entry's own RDN with the escapes removed: `cn=Meeting Room 1,ou=resources,…`
+gives `Meeting Room 1`, and `o=Room 12,ou=resources,…` gives `Room 12`. The
+creation, the update and the deletion hooks all read it that way, so the three
+name the same resource; an entry whose DN yields no value is not synchronised.
+
+Only entries in `DM_CALENDAR_RESOURCE_BASE` are synchronised, on all three
+hooks. `DM_CALENDAR_RESOURCE_OBJECTCLASS` filters creations only: a
+modification carries the attributes that changed, so an untouched objectClass
+is not there to compare, and a deleted entry cannot be read any more. The
+branch is the guard that remains on those two paths.
+
+Renaming an entry changes its RDN, hence its id: Calendar is not told, and the
+resource keeps its former id there.
 
 ### Resource Data Format
 
@@ -103,7 +159,7 @@ DM_LDAP_FLAT_SCHEMA="/path/to/calendar-resources-schema.json"
 3. Add the plugin to `DM_PLUGINS`:
 
    ```bash
-   DM_PLUGINS="core/ldap/onChange,core/ldap/flatGeneric,twake/calendarResources"
+   DM_PLUGINS="core/ldap/onChange,core/ldap/flatGeneric,twake/calendar"
    ```
 
 4. Start ldap-rest - resources will be automatically synced
@@ -121,7 +177,7 @@ Example log:
 
 ```json
 {
-  "plugin": "calendarResources",
+  "plugin": "calendar",
   "event": "ldapcalendarResourceadddone",
   "result": "success",
   "http_status": 201,
@@ -138,6 +194,7 @@ Example log:
 2. Verify that `DM_CALENDAR_WEBADMIN_TOKEN` is valid
 3. Check logs for API errors
 4. Ensure the ldapFlat schema has `entity.name` set to `calendarResource`
+5. Ensure `DM_CALENDAR_RESOURCE_BASE` is the full DN of the branch the entries are in: a partial value matches no entry, and the plugin says so at startup
 
 ### Authentication errors
 
@@ -145,22 +202,21 @@ Ensure `DM_CALENDAR_WEBADMIN_TOKEN` is set and valid. The token is sent as a Bea
 
 ### Wrong resources being synced
 
-Use `DM_CALENDAR_RESOURCE_BASE` and `DM_CALENDAR_RESOURCE_OBJECTCLASS` to filter which LDAP entries are considered resources.
+Use `DM_CALENDAR_RESOURCE_BASE` and `DM_CALENDAR_RESOURCE_OBJECTCLASS` to filter which LDAP entries are considered resources. Note that the objectClass filter only applies to creations, so an entry of the resource entity that must never reach Calendar has to sit outside the branch.
 
 ## Public Methods
 
-Public methods available on the CalendarResources plugin instance.
+Public methods available on the Calendar plugin instance.
 
 ### Usage
 
 ```typescript
 import type { DM } from 'ldap-rest';
-import type CalendarResources from 'ldap-rest/plugin-twake-calendarresources';
+import type Calendar from 'ldap-rest/plugin-twake-calendar';
 
 // Get the plugin instance from another plugin
-const calendar = this.server.getPlugin(
-  'calendarResources'
-) as CalendarResources;
+// (declare `dependencies = { calendar: 'core/twake/calendar' }` so it loads first)
+const calendar = this.requirePlugin<Calendar>('calendar');
 ```
 
 ### deleteUserData(mail)
@@ -182,7 +238,8 @@ async deleteUserData(mail: string): Promise<{ taskId: string } | null>
 **Example:**
 
 ```typescript
-const result = await calendar.deleteUserData('user@example.com');
+// requirePlugin() returns null when the plugin is not loaded
+const result = await calendar?.deleteUserData('user@example.com');
 if (result) {
   console.log(`Deletion task started: ${result.taskId}`);
 }

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

@@ -4,17 +4,19 @@ Plugins for LDAP entity management.
 
 ## Overview
 
-| Plugin                                | Entity                   | Features                            |
-| ------------------------------------- | ------------------------ | ----------------------------------- |
-| [flat-generic](flat-generic.md)       | Users, Positions, Custom | Schema-driven, Validation, Pointers |
-| [groups](groups.md)                   | Groups                   | Member validation, Nested groups    |
-| [organizations](organizations.md)     | Organizational Units     | Tree navigation, Search             |
-| [bulk-import](bulk-import.md)         | All (bulk operations)    | CSV import, Template generation     |
-| [trash](trash.md)                     | All (soft delete)        | Trash system, Recovery              |
-| [external-users](external-users.md)   | Contacts                 | Automatic creation                  |
-| [on-change](on-change.md)             | All                      | Change detection                    |
-| [password-policy](password-policy.md) | Password management      | Expiration, Lockout, Unlock         |
-| [raw](raw.md)                         | Whole directory (read)   | Root DSE, Schema, Tree, Raw search  |
+| Plugin                                    | Entity                   | Features                                |
+| ----------------------------------------- | ------------------------ | --------------------------------------- |
+| [flat-generic](flat-generic.md)           | Users, Positions, Custom | Schema-driven, Validation, Pointers     |
+| [groups](groups.md)                       | Groups                   | Member validation, Nested groups        |
+| [organizations](organizations.md)         | Organizational Units     | Tree navigation, Search                 |
+| [bulk-import](bulk-import.md)             | All (bulk operations)    | CSV import, Template generation         |
+| [trash](trash.md)                         | All (soft delete)        | Trash system, Recovery                  |
+| [external-users](external-users.md)       | Contacts                 | Automatic creation                      |
+| [on-change](on-change.md)                 | All                      | Change detection                        |
+| [enterprise-rules](enterprise-rules.md)   | All (business rules)     | Uniqueness, Mail domains, Delete guards |
+| [account-lifecycle](account-lifecycle.md) | Accounts                 | Enable/disable, Password reset          |
+| [password-policy](password-policy.md)     | Password management      | Expiration, Lockout, Unlock             |
+| [raw](raw.md)                             | Whole directory (read)   | Root DSE, Schema, Tree, Raw search      |
 
 ## API Endpoints
 

package/docs/usage/plugins/ldap/account-lifecycle.md

@@ -0,0 +1,129 @@
+# LDAP Account Lifecycle Plugin
+
+The two account operations an administrator performs most often — change an
+account's state, and reset its password — as first-class endpoints.
+
+Both are expressed against semantic roles, never attribute names. What
+"disabled" _is_ in a given directory — a DN in a nomenclature, a string, a
+boolean — is schema configuration.
+
+## Configuration
+
+```bash
+--plugin core/ldap/accountLifecycle
+```
+
+The plugin loads `core/ldap/flatGeneric` if it is not already there, and adds
+endpoints to each entity whose schema asks for them:
+
+- `POST /api/v1/ldap/{pluralName}/{id}/status` when the schema declares an
+  `accountStatus` attribute carrying named `states`
+- `POST /api/v1/ldap/{pluralName}/{id}/password` when it declares a `password`
+  attribute
+
+Changes go through the entity's own modify path, so schema validation, hooks
+and authorization apply exactly as they do to any other update.
+
+## Declaring the states
+
+```json
+{
+  "twakeAccountStatus": {
+    "type": "pointer",
+    "branch": ["ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com"],
+    "role": "accountStatus",
+    "generated": true,
+    "default": "cn=active,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+    "states": {
+      "enabled": "cn=active,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+      "disabled": "cn=disabled,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+      "noAccess": "cn=noaccess,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+      "toDelete": "cn=todelete,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com"
+    }
+  }
+}
+```
+
+`enabled` and `disabled` are the names the API speaks; a deployment adds its
+own freely. `default` is what a new account gets, applied by
+[enterprise-rules](enterprise-rules.md).
+
+## Changing the state
+
+```bash
+curl -X POST http://localhost:8081/api/v1/ldap/users/alice/status \
+  -H 'Content-Type: application/json' \
+  -d '{"state": "disabled"}'
+```
+
+```json
+{ "success": true, "state": "disabled" }
+```
+
+An unknown state is refused with a `400` that names the ones this directory
+knows, so a client never has to hardcode the list:
+
+```json
+{
+  "error": "Unknown state \"retired\" for user; known states: enabled, disabled, noAccess, toDelete"
+}
+```
+
+## Resetting the password
+
+```bash
+curl -X POST http://localhost:8081/api/v1/ldap/users/alice/password \
+  -H 'Content-Type: application/json' -d '{}'
+```
+
+```json
+{ "success": true, "generated": true, "forceChange": true, "password": "xY3k…" }
+```
+
+With no `password` in the body, one is generated and returned **once** — the
+credential attributes are marked `neverReturn` in the schema precisely so a
+later read cannot hand it back. Supply `password` to set a chosen one; the
+answer then carries `"generated": false` and does not echo it.
+
+A `password` that is present has to be a non-empty string. An empty one — or
+`null`, or anything that is not text — is refused with a `400`:
+
+```json
+{
+  "error": "Field password must be a non-empty string; omit it to have one generated"
+}
+```
+
+It used to be taken as an absent one, so `{"password": ""}` answered
+`success` after setting a random credential the caller never saw: a client
+that emptied the field by accident believed it had set the password it typed.
+Omitting the field is how a generated password is asked for.
+
+`forceChange` (true by default) also writes the `passwordReset`-role attribute
+so the directory asks for a new password at next login. For a boolean
+attribute the values written are `TRUE` and `FALSE`; a directory that spells
+them otherwise says so through `states.required` and `states.cleared`.
+
+| Field         | Meaning                                             |
+| ------------- | --------------------------------------------------- |
+| `generated`   | The server chose the password                       |
+| `password`    | Present only when generated                         |
+| `forceChange` | Whether the "change at next login" flag was written |
+
+> **Note** — `pwdReset` is an operational attribute of the OpenLDAP `ppolicy`
+> overlay. Writing it requires the overlay to be loaded; without it the
+> directory answers `attribute type undefined`.
+
+## Errors
+
+| Status | When                                                           |
+| ------ | -------------------------------------------------------------- |
+| `400`  | Unknown state, or a body with no `state`                       |
+| `400`  | A `password` that is present but empty, `null` or not a string |
+| `404`  | No such account                                                |
+
+## See also
+
+- [flat-generic](flat-generic.md) — `role`, `states` and `neverReturn`
+- [enterprise-rules](enterprise-rules.md) — the default state of a new account
+- [password-policy](password-policy.md) — expiry, lockout and complexity

package/docs/usage/plugins/ldap/bulk-import.md

@@ -137,6 +137,13 @@ jdoe,John Doe,Doe,John,john.doe@example.com,password123,ou=IT,ou=organization,dc
 asmith,Alice Smith,Smith,Alice,alice.smith@example.com,secret456,ou=HR,ou=organization,dc=example,dc=com
 ```
 
+A value must sit under a column whose name is a syntactically valid LDAP
+attribute name (`mail`, `2.5.4.3`, `cn;lang-fr`). Otherwise its line fails
+with `Invalid column name` and is counted in `failed`. The check is on syntax
+only: an unknown attribute such as `maill` passes it and fails on the
+directory side. Empty cells are ignored whatever their column is called, so a
+comment column left empty, or a trailing comma, does not prevent the import.
+
 ### Special Column: `organizationDn`
 
 The `organizationDn` column is special and triggers automatic calculation of:
@@ -289,7 +296,7 @@ mail: john.doe@example.com
 userPassword: {SSHA}...
 telephoneNumber: +1-555-0100
 twakeDepartmentLink: ou=Engineering,ou=organization,dc=example,dc=com
-twakeDepartmentPath: Engineering / organization
+twakeDepartmentPath: Engineering
 ```
 
 ## Operation Modes

package/docs/usage/plugins/ldap/enterprise-rules.md

@@ -0,0 +1,167 @@
+# LDAP Enterprise Rules Plugin
+
+The business rules an enterprise directory needs on top of per-attribute
+validation: uniqueness across a shared namespace, mail addresses confined to
+the domains an organization owns, computed organization paths, normalised
+quotas, and referential-integrity guards on deletion.
+
+Every rule is driven by the loaded entity schemas. The plugin contains no
+attribute name, no domain and no nomenclature value, so the same code serves a
+directory laid out differently without a change.
+
+## Configuration
+
+```bash
+--plugin core/ldap/enterpriseRules
+```
+
+It reads the schemas already loaded by `core/ldap/flatGeneric`,
+`core/ldap/groups` and `core/ldap/organizations`, so load it alongside them.
+The organizations plugin only exposes its schema when one is given:
+
+```bash
+--organization-schema ./static/schemas/twake/organizations.json
+```
+
+| Option                               | Default             | Purpose                                                             |
+| ------------------------------------ | ------------------- | ------------------------------------------------------------------- |
+| `--enterprise-domain-name-attribute` | `associatedDomain`  | Fallback when no loaded schema declares a `domainName` role         |
+| `--enterprise-domain-link-attribute` | _(from the schema)_ | Fallback when the organization schema declares no `domainLink` role |
+| `--group-dummy-user`                 | `cn=fakeuser`       | Placeholder member that does not count towards `deleteGuard`        |
+
+## Order of evaluation
+
+Checks run **before** transformations, inside the same hook. A check therefore
+always sees the payload as the client sent it: uniqueness and domain rules
+validate the address that was submitted, never one the server has already
+rewritten, and an identifier derived from that address cannot influence the
+check that justified it.
+
+## Rules
+
+### Uniqueness
+
+```json
+{
+  "employeeNumber": { "type": "string", "unique": true },
+  "mail": {
+    "type": "string",
+    "role": "primaryEmail",
+    "unique": {
+      "attributes": ["mailAlternateAddress"],
+      "branches": ["dc=example,dc=com"]
+    }
+  }
+}
+```
+
+- `attributes` names the other attributes sharing the value namespace — a mail
+  address must not already be someone's alias.
+- `branches` widens the search beyond the entity's own branch, which is what
+  makes an address unique across accounts _and_ distribution lists.
+- `sentinel` exempts one value, for directories that use a placeholder on
+  non-individual entries.
+- `filter` narrows the search, e.g. `(objectClass=twakeAccount)`.
+
+On an update the entry being modified is excluded from the search, so
+re-sending an unchanged value never conflicts with itself.
+
+### Mail domains
+
+```json
+{
+  "mail": {
+    "mailDomainScope": "organization",
+    "allowSubdomains": true
+  }
+}
+```
+
+`organization` walks up from the entry's `organizationLink`, collecting the
+domains each ancestor declares through its `domainLink` role, up to the root of
+the tree. `directory` accepts any domain declared anywhere. When nobody
+declares a domain, no restriction applies; a domain entry whose name is `*`
+authorises every domain.
+
+The host is taken after the **last** `@`, so a domain that merely ends with an
+authorised one (`evil-example.org` against `example.org`) is refused.
+`allowSubdomains` is what lets a distribution list live at
+`all@lists.example.org` under an organization that owns `example.org`.
+
+### Computed organization path
+
+An entity declaring both an `organizationLink` and an `organizationPath` role
+gets its path filled from the organization it points at, on creation and
+whenever the link changes. Mark the path `generated` so a client cannot set it.
+
+### Normalised sizes
+
+```json
+{
+  "mailQuotaSize": {
+    "type": "number",
+    "normalize": "byteSize",
+    "default": 1000000000,
+    "hint": "Expected pattern xGB, xMB, xKB or a number of bytes"
+  }
+}
+```
+
+`5GB`, `500 MB`, `2KB` and `2048` all become a number of bytes, with decimal
+multipliers (1 GB = 10⁹ bytes) as mail servers count them. The same conversion
+applies to creations and to updates.
+
+### Server-owned defaults
+
+On creation, an attribute that is `generated` or `normalize`d and carries a
+`default` is filled when the client said nothing — which is how a new account
+lands in its initial state:
+
+```json
+{
+  "twakeAccountStatus": {
+    "type": "pointer",
+    "role": "accountStatus",
+    "generated": true,
+    "default": "cn=active,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com"
+  }
+}
+```
+
+### Scheduled removal
+
+An `accountExpiry` attribute must not carry a date already past. The comparison
+is against the start of the current day, so scheduling something for today is
+allowed.
+
+### Deletion guards
+
+```json
+{
+  "title": { "type": "pointer", "referentialIntegrity": "restrict" },
+  "member": { "type": "array", "role": "members", "deleteGuard": "nonEmpty" }
+}
+```
+
+- `referentialIntegrity: "restrict"` refuses to delete an entry while another
+  entry still points at it — a position somebody still holds, a nomenclature
+  value still in use. Declared on the **referencing** attribute, and the
+  pointer's `branch` tells the plugin which deletions to check.
+- `deleteGuard: "nonEmpty"` refuses to delete a group that still has members.
+  The placeholder member some directories keep to satisfy `groupOfNames`
+  (`--group-dummy-user`) does not count.
+
+Both default to off: a deployment turns them on where it wants them.
+
+## Errors
+
+| Status | When                                                                          |
+| ------ | ----------------------------------------------------------------------------- |
+| `400`  | A size that is not a size, a date already past                                |
+| `409`  | A duplicate value, a mail domain outside the authorised set, a guarded delete |
+
+## See also
+
+- [flat-generic](flat-generic.md) — the schema format these markers extend
+- [account-lifecycle](account-lifecycle.md) — status changes and password resets
+- [organizations](organizations.md) — the tree the domain rule walks up