ldap-rest 0.6.2 → 0.8.0

package/docs/usage/directory-audit.md

@@ -0,0 +1,105 @@
+# Auditing a directory before a migration
+
+Tightening a validation pattern changes what the server accepts **from now
+on**. It says nothing about the entries already stored: a directory whose
+addresses were never anchored, or whose organization names predate the rule
+that now governs them, loads fine and then refuses the first update of every
+offending entry — which is discovered one support ticket at a time.
+
+`npm run audit:directory` reads a branch as it is and reports what the schema
+would refuse, so the work is known before the switch rather than after it.
+
+## Running it
+
+```sh
+export DM_LDAP_URL=ldap://directory.example.org
+export DM_LDAP_DN='cn=admin,dc=example,dc=com'
+export DM_LDAP_PWD='…'
+export DM_LDAP_BASE='dc=example,dc=com'
+
+npm run audit:directory -- --schema static/schemas/twake/users.json \
+  --plugin core/ldap/enterpriseRules
+```
+
+| Option            | Default                      | Purpose                             |
+| ----------------- | ---------------------------- | ----------------------------------- |
+| `--schema`        | _(required)_                 | Schema to check against             |
+| `--base`          | the schema's own entity base | Branch to read                      |
+| `--filter`        | `(objectClass=*)`            | Narrows what is audited             |
+| `--url`           | `DM_LDAP_URL`                | Directory to read                   |
+| `--bind-dn`       | `DM_LDAP_DN`                 | Identity to read with               |
+| `--bind-password` | `DM_LDAP_PWD`                | Its password                        |
+| `--samples`       | `5`                          | Offending entries named per finding |
+| `--plugin`        | _(none)_                     | A plugin the server loads, repeated |
+
+`--plugin` matters for the attributes a schema marks both `required` and
+`generated`. The server exempts one from its check only when something fills
+it: the entity itself (`generatedFrom`), or a loaded plugin. Name the plugins
+the server loads and the audit exempts what they fill; without them it reports
+those attributes as `missing, and no --plugin fills it` — which is what every
+creation would be refused for on a server that does not load them.
+
+It exits `0` when the branch is clean, `1` when the schema would refuse
+something, and `2` when the audit itself could not run — an unreadable schema,
+a directory that would not answer — so a pipeline can tell "dirty" from
+"broken" rather than gating on both alike.
+
+`--bind-password` puts the password in `ps` and in the shell history of
+whoever runs it. `DM_LDAP_PWD` is the path to prefer, and the flag is there
+for parity with the server's own `--ldap-pwd`.
+
+## What it checks, and what only the server can
+
+The audit reads a schema and an entry, so it answers what an entry alone can
+answer: required attributes, the `test` pattern of a value and of an array's
+elements, and the branch a DN must land in. It replaces `__KEY__` placeholders
+and `{config_key}` in `entity.base` from the `DM_*` environment exactly as the
+server does, leaving a placeholder the configuration does not name.
+
+What it does not answer needs the rest of the directory, and belongs to a dry
+run rather than here: uniqueness across a namespace, the mail domains an
+organization owns, and anything a plugin computes after validation. A clean
+audit is not a promise that every entry will survive every rule — it is a
+promise that none of them fails on its own contents.
+
+## Reading the report
+
+```
+12632 entries read, 47 value(s) the schema would refuse:
+
+  mail: does not match — 41
+    expected: Expected an address in the example.org domain, at most 64 characters before the @
+    uid=jean.dupont,ou=users,dc=example,dc=com → "jean.dupont@old-domain.example"
+    …and 36 more
+
+  postalCode: does not match — 6
+    expected: Expected pattern 9999, A9999 or R9999
+    uid=marie.martin,ou=users,dc=example,dc=com → "1234"
+```
+
+Each finding names the attribute, why it was refused, and — from the schema's
+`hint` — what a valid value looks like. The same wording reaches the person
+filling the form, so the fix and the rule are described identically.
+
+## What it checks, and what it cannot
+
+Checked, because an entry answers for itself:
+
+- `test` patterns, on single and multi-valued attributes
+- `required` attributes that are absent — except the ones the server computes
+  (`generated`), which an entry is not expected to carry yet
+- the `branch` a `pointer` must land in
+
+Not checked, because it takes the whole directory or a live server:
+
+- uniqueness across a shared namespace
+- mail addresses against the domains an organization owns
+- anything a hook computes rather than validates
+
+For those, run the target configuration against a copy of the directory and
+replay the writes.
+
+## See also
+
+- [flat-generic](plugins/ldap/flat-generic.md) — where `test` and `hint` live
+- [enterprise-rules](plugins/ldap/enterprise-rules.md) — the rules a dry run covers

package/docs/usage/plugins/README.md

@@ -52,12 +52,12 @@ Protection and rate limiting:
 
 Connect to external systems:
 
-| Plugin                                                   | Description                  |
-| -------------------------------------------------------- | ---------------------------- |
-| [james-mail](integrations/james-mail.md)                 | Apache James synchronization |
-| [james-mailboxes](integrations/james-mailboxes.md)       | Apache James team mailboxes  |
-| [calendar-resources](integrations/calendar-resources.md) | Twake calendar resources     |
-| [app-accounts](integrations/app-accounts.md)             | Applicative accounts API     |
+| Plugin                                             | Description                        |
+| -------------------------------------------------- | ---------------------------------- |
+| [james-mail](integrations/james-mail.md)           | Apache James synchronization       |
+| [james-mailboxes](integrations/james-mailboxes.md) | Apache James team mailboxes        |
+| [calendar](integrations/calendar.md)               | Twake Calendar resources and users |
+| [app-accounts](integrations/app-accounts.md)       | Applicative accounts API           |
 
 ## Utility Plugins
 

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

@@ -14,11 +14,12 @@ LDAP-Rest provides multiple authentication plugins to secure API access. These p
 
 ## Authorization Plugins
 
-| Method                                          | Plugin                     | Description                 |
-| ----------------------------------------------- | -------------------------- | --------------------------- |
-| [Authorization Per Branch](authz-per-branch.md) | `core/auth/authzPerBranch` | Branch-level access control |
-| [Authorization Per Route](authz-per-route.md)   | `core/auth/authzPerRoute`  | HTTP route-level ACL        |
-| [Authorization LinID 1.x](authz-linid1.md)      | `core/auth/authzLinid1`    | LinID 1.x integration       |
+| Method                                          | Plugin                     | Description                  |
+| ----------------------------------------------- | -------------------------- | ---------------------------- |
+| [Authorization Per Branch](authz-per-branch.md) | `core/auth/authzPerBranch` | Branch-level access control  |
+| [Authorization Per Route](authz-per-route.md)   | `core/auth/authzPerRoute`  | HTTP route-level ACL         |
+| [Authorization LinID 1.x](authz-linid1.md)      | `core/auth/authzLinid1`    | LinID 1.x integration        |
+| [Authorization Scope](authz-scope.md)           | `core/auth/authzScope`     | What the current user may do |
 
 ## Security Plugins
 

package/docs/usage/plugins/auth/authz-scope.md

@@ -0,0 +1,103 @@
+# Authorization Scope Plugin
+
+Tells a client what the signed-in administrator may actually do, before it
+offers them a button that will fail.
+
+In a local-administration model the scope _is_ the interface: a manager
+administers a few branches of the tree and nothing else, and an application
+that cannot name those branches leaves them guessing. This endpoint answers
+both halves — which branches, and which entities can be created — by asking
+whichever authorization plugin is in force.
+
+## Configuration
+
+```bash
+--plugin core/auth/authzScope
+```
+
+It has no options. It answers through whichever loaded plugin carries the
+`authz` role _and_ can say who may do what where — one implementing
+`resolveUser`, `getAuthorizedBranches` and `getUserPermissions`. Both
+[authz-linid1](authz-linid1.md) and [authz-per-branch](authz-per-branch.md)
+do, and this endpoint works with either without knowing which.
+
+The role alone is not enough. [authz-per-route](authz-per-route.md) gates URLs
+and [authz-dynamic](authz-dynamic.md) reads a token: both carry the `authz`
+role and implement none of those three methods, so this endpoint passes them
+over — loading one beside a branch-level plugin changes the answer not at all.
+A server whose only authorization plugin is one of those has nothing to
+describe a scope with, and the answer is the unrestricted one shown below: a
+client built on it shows every button, and a refusal, when it comes, comes from
+the route or the token rather than from the scope.
+
+## Endpoint
+
+```
+GET /api/v1/authz/scope
+```
+
+```json
+{
+  "user": "uid=alice,ou=users,dc=example,dc=com",
+  "unrestricted": false,
+  "branches": [
+    {
+      "dn": "ou=Sales,ou=organization,dc=example,dc=com",
+      "name": "Sales",
+      "path": "Acme / Sales",
+      "read": true,
+      "write": true,
+      "delete": true
+    }
+  ],
+  "entities": [
+    { "name": "users", "base": "ou=users,dc=example,dc=com", "create": true },
+    { "name": "groups", "base": "ou=groups,dc=example,dc=com", "create": true },
+    {
+      "name": "organizations",
+      "base": "ou=organization,dc=example,dc=com",
+      "create": false
+    }
+  ]
+}
+```
+
+`name` and `path` come from the branch entry itself, so an interface can show
+the scope in the directory's own words rather than as a raw DN.
+
+`create` answers "may I add one of these?", on the rule the add hook enforces.
+An entry that can carry the organization link (its schema declares the
+configured link attribute) is scoped by the organization it is attached to, so
+the answer is yes as soon as the caller may write in a branch they administer.
+One that cannot — a position, a nomenclature row — is checked against the
+branch it lands in, so the answer is whether the caller may write there.
+Organizations are the other exception, since they live in the tree itself and
+need write permission on the node they hang from — the top of the tree, which
+is where a new organization goes when the client names no parent. A local administrator of one branch therefore reads
+`create: false` for organizations, and creates sub-organizations under their own
+node by naming it as `parentDn`.
+
+With no authorization plugin loaded the server grants everything, and the
+answer says so:
+
+```json
+{
+  "user": "alice",
+  "unrestricted": true,
+  "branches": [],
+  "entities": [
+    { "name": "users", "base": "ou=users,dc=example,dc=com", "create": true }
+  ]
+}
+```
+
+## Errors
+
+| Status | When                                                          |
+| ------ | ------------------------------------------------------------- |
+| `401`  | No authenticated user, or a user the directory cannot resolve |
+
+## See also
+
+- [authz-linid1](authz-linid1.md) — the local-administrator model this serves
+- [authz-per-branch](authz-per-branch.md) — static per-branch permissions

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

@@ -21,6 +21,23 @@ DM_LLNG_INI="/etc/lemonldap-ng/lemonldap-ng.ini"
 2. **LLNG Configuration**: Valid `lemonldap-ng.ini` file
 3. **Virtual Host Configuration**: LDAP-Rest must be configured as a protected application in LLNG
 
+The handler runs inside LDAP-Rest and reads `lemonldap-ng.ini` when the server
+starts. The file tells it where the LLNG configuration is, and which virtual
+hosts it protects — a Node.js handler serves only those listed in
+`nodeVhosts`:
+
+```ini
+[configuration]
+type = REST
+baseConfigUrl = https://auth.example.com/index.fcgi/config
+
+[node-handler]
+nodeVhosts = api.example.com
+```
+
+A file that cannot be read, a configuration that cannot be reached or a
+missing `nodeVhosts` stops the server at startup, with the reason.
+
 ## How It Works
 
 1. Uses the LemonLDAP::NG Handler to validate requests

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}`);
 }