ldap-rest 0.9.0 → 0.10.0

package/docs/usage/plugins/auth/authz-per-branch.md

@@ -174,10 +174,20 @@ Modifies the organization tree API:
 
 Groups are resolved dynamically:
 
-1. Searches for all groups where user is a member
-2. Uses wildcard DN pattern: `(member=uid={user},*)`
-3. Caches results for configured TTL (default: 60 seconds)
-4. Cache prevents repeated LDAP queries for same user
+1. Resolves the caller to its DN, searching
+   `(<ldap_user_main_attribute>=<uid>)` under the LDAP base (`--ldap-base`)
+2. Searches for all groups where that DN is a member
+3. Matches each group found against the `groups` keys **as DNs**: case and
+   the spaces around `,` and `=` do not matter, so
+   `CN=Editors, OU=Groups,dc=example,dc=com` names the same group as
+   `cn=editors,ou=groups,dc=example,dc=com`
+4. Caches results (see [Group Caching](#group-caching)); concurrent
+   requests for the same user share one lookup
+
+A uid that names **more than one** entry gets **no group rule**, since its
+groups cannot be told apart from its homonym's; a warning is logged, and the
+uid's own `users` rule still applies. A lookup that fails answers `500` and
+is not cached.
 
 ## Sub-branch Inheritance
 
@@ -379,6 +389,10 @@ Group memberships are cached to reduce LDAP queries:
 - **Configurable**: `--authz-per-branch-cache-ttl`
 - **Per-user cache**: Each user's groups cached separately
 - **Automatic expiry**: Cache entries expire after TTL
+- **Dropped on writes**: any add, delete, rename or move made through
+  ldap-rest empties the cache, and so does a modify touching the group member
+  attribute or `--ldap-user-main-attribute`. A change made directly in the
+  directory waits for the TTL
 
 Cache hit/miss logging:
 
@@ -420,7 +434,6 @@ names, this plugin lets them read and refuses every write. Give it an
 
 - Group DNs must be fully qualified
 - Group resolution uses LDAP search - ensure proper indexing
-- Cache can delay permission revocation (up to TTL duration)
 
 ### Authentication Required
 
@@ -531,7 +544,8 @@ Changed permissions don't take effect immediately.
 
 **Solutions:**
 
-1. Wait for group cache TTL to expire
+1. A membership changed directly in the directory waits for the
+   [group cache](#group-caching) TTL
 2. Restart server to clear all caches
 3. Reduce `--authz-per-branch-cache-ttl` for testing
 
@@ -542,17 +556,25 @@ User should inherit group permissions but doesn't.
 
 **Solutions:**
 
-1. Verify user is member of group:
+1. Verify the user's DN is a member of the group:
 
    ```bash
-   ldapsearch -x -b "ou=groups,dc=example,dc=com" "(member=uid=jdoe,*)"
+   ldapsearch -x -b "dc=example,dc=com" \
+     "(member=uid=jdoe,ou=users,dc=example,dc=com)"
    ```
 
-2. Check group DN in config matches LDAP exactly
+2. Check the group DN in config names the group: it is compared as a DN
+   (case and spaces are ignored), but every RDN must be there
 
-3. Ensure group membership uses correct attribute (default: `member`)
+3. Check the uid names a single entry:
 
-4. Configure custom member attribute if needed:
+   ```bash
+   ldapsearch -x -b "dc=example,dc=com" "(uid=jdoe)" dn
+   ```
+
+4. Ensure group membership uses correct attribute (default: `member`)
+
+5. Configure custom member attribute if needed:
    ```bash
    --ldap-group-member-attribute uniqueMember
    ```

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

@@ -150,6 +150,11 @@ identified caller of the same server is told. A server loading no
 authorization plugin at all answers `unrestricted` to anyone, anonymous
 included, which is what it does.
 
+An identity that names **several** entries — the same `uid` in two branches of
+a directory without the `unique` overlay, which `authzLinid1` refuses with
+`AmbiguousIdentityError` — is answered `403`, not `401`: the caller cannot be
+told apart from the homonym, so no scope can be described for them.
+
 ## See also
 
 - [authz-linid1](authz-linid1.md) — the local-administrator model this serves

package/docs/usage/plugins/ldap/on-change.md

@@ -1,10 +1,7 @@
 # LDAP onChange Plugin
 
-Monitor LDAP attribute changes and trigger hooks for specific attributes.
-
-## Overview
-
-The `onChange` plugin watches for LDAP modifications and generates specialized hooks when configured attributes change. This enables reactive integrations with external systems (mail servers, quota managers, etc.).
+Publish the state of an entry before and after each write made through
+LDAP-Rest, and hooks for the attributes other plugins follow.
 
 ## Configuration
 
@@ -14,305 +11,75 @@ The `onChange` plugin watches for LDAP modifications and generates specialized h
 --quota-attribute mailQuota
 ```
 
-**Environment Variables:**
-
-```bash
-DM_MAIL_ATTRIBUTE="mail"
-DM_QUOTA_ATTRIBUTE="mailQuota"
-```
-
-## Generated Hooks
-
-The plugin generates hooks based on configured attributes:
-
-| Config Parameter    | Generated Hook      | Parameters                       |
-| ------------------- | ------------------- | -------------------------------- |
-| `--mail-attribute`  | `onLdapMailChange`  | `(dn, oldMail, newMail)`         |
-| `--quota-attribute` | `onLdapQuotaChange` | `(dn, mail, oldQuota, newQuota)` |
-
-Generic hook for any change:
-
-- `onLdapChange` - `(dn, changes)` where `changes` is `Record<attr, [oldValue, newValue]>`
-
-## How It Works
-
-1. **Hooks into LDAP modify operations** via `ldapUsersmodify` and `ldapGroupsmodify` hooks
-2. **Detects attribute changes** by comparing old and new values
-3. **Triggers specialized hooks** for configured attributes
-4. **Provides old and new values** to downstream hooks
-
-## Use Cases
-
-### Mail Server Synchronization
-
-When user email changes, update external mail server:
-
-```javascript
-// In another plugin
-hooks: {
-  onLdapMailChange: async (dn, oldMail, newMail) => {
-    await mailServer.renameAccount(oldMail, newMail);
-    console.log(`Renamed mail account: ${oldMail} → ${newMail}`);
-  };
-}
-```
-
-### Quota Management
-
-When quota changes, update mail server quota:
-
-```javascript
-hooks: {
-  onLdapQuotaChange: async (dn, mail, oldQuota, newQuota) => {
-    await mailServer.setQuota(mail, newQuota);
-    console.log(`Updated quota for ${mail}: ${oldQuota} → ${newQuota}`);
-  };
-}
-```
-
-### Generic Change Tracking
-
-Track all attribute changes:
-
-```javascript
-hooks: {
-  onLdapChange: async (dn, changes) => {
-    for (const [attr, [oldVal, newVal]] of Object.entries(changes)) {
-      console.log(`${dn}: ${attr} changed from ${oldVal} to ${newVal}`);
-    }
-  };
-}
-```
-
-## Examples
-
-### Example 1: Mail Attribute Monitoring
-
-```bash
---plugin core/ldap/onChange \
---plugin core/ldap/flatGeneric \
---ldap-flat-schema ./schemas/users.json \
---mail-attribute mail
-```
-
-When a user's mail attribute changes via API:
-
-```bash
-PUT /api/v1/ldap/users/jdoe
-{
-  "replace": {
-    "mail": "john.doe@newdomain.com"
-  }
-}
-```
-
-The `onLdapMailChange` hook fires with:
-
-- `dn`: `"uid=jdoe,ou=users,dc=example,dc=com"`
-- `oldMail`: `"jdoe@olddomain.com"`
-- `newMail`: `"john.doe@newdomain.com"`
-
-### Example 2: Multiple Attributes
-
-```bash
---plugin core/ldap/onChange \
---mail-attribute mail \
---quota-attribute mailQuota
-```
-
-When both attributes change:
+## Hooks
 
-```bash
-PUT /api/v1/ldap/users/jdoe
-{
-  "replace": {
-    "mail": "jdoe@company.com",
-    "mailQuota": "5000000000"
-  }
-}
-```
+`onLdapEntryChange(dn, before, after, context)` fires after every add,
+modify, rename and delete, with the entry as the directory held it on each
+side:
 
-Both hooks fire:
+| Operation | `before`                 | `after`                  |
+| --------- | ------------------------ | ------------------------ |
+| add       | `null`                   | the new entry            |
+| modify    | the entry before         | the entry after          |
+| rename    | the entry, at its old DN | the entry, at its new DN |
+| delete    | the entry before         | `null`                   |
 
-1. `onLdapMailChange(dn, "old@mail.com", "jdoe@company.com")`
-2. `onLdapQuotaChange(dn, "jdoe@company.com", "1000000000", "5000000000")`
+`dn` is the entry's DN after the write, its old one on a delete. `context`
+says who made the write, and through which door:
 
-### Example 3: Generic Change Listener
+- `actor`: the caller's `userName`, or its `user` when it has none;
+- `requestId`: generated, the same for every write of one request;
+- `source`: `scim` for the SCIM API, `rest` otherwise.
 
-```bash
---plugin core/ldap/onChange
-```
+A write no request is behind, such as a scheduled task's, gets `{}`. The LDAP
+`ldap*done` hooks receive the same context after their arguments.
 
-All modifications trigger `onLdapChange`:
+The other hooks are derived from it:
 
-```bash
-PUT /api/v1/ldap/users/jdoe
-{
-  "replace": {
-    "cn": "John A. Doe",
-    "telephoneNumber": "+1234567890"
-  },
-  "delete": ["description"]
-}
-```
+| Hook                      | Fires when                                                 | Parameters                             |
+| ------------------------- | ---------------------------------------------------------- | -------------------------------------- |
+| `onLdapChange`            | any attribute changed                                      | `(dn, changes)`                        |
+| `onLdapMailChange`        | `--mail-attribute` changed                                 | `(dn, oldMail, newMail)`               |
+| `onLdapQuotaChange`       | `--quota-attribute` changed                                | `(dn, mail, oldQuota, newQuota)`       |
+| `onLdapAliasChange`       | `--alias-attribute` changed                                | `(dn, mail, oldAliases, newAliases)`   |
+| `onLdapForwardChange`     | `--forward-attribute` changed                              | `(dn, mail, oldForwards, newForwards)` |
+| `onLdapDriveQuotaChange`  | `--drive-quota-attribute` changed                          | `(dn, oldQuota, newQuota)`             |
+| `onLdapDisplayNameChange` | the name built from `cn`, or `givenName` and `sn`, changed | `(dn, oldName, newName)`               |
 
-Hook receives:
+`changes` maps each attribute that changed to `[oldValues, newValues]`, the
+full values on each side, `null` where the attribute is absent:
 
-```javascript
-{
-  "cn": ["John Doe", "John A. Doe"],
-  "telephoneNumber": [null, "+1234567890"],
-  "description": ["Old description", null]
-}
+```text
+member was [a, b], the request added c:
+{ member: [['a', 'b'], ['a', 'b', 'c']] }
 ```
 
-## Integration Examples
-
-### With Twake James Mail Server
-
-```bash
---plugin core/ldap/onChange \
---plugin twake/james \
---plugin core/ldap/flatGeneric \
---ldap-flat-schema ./schemas/twake/users.json \
---mail-attribute mail \
---quota-attribute mailQuota \
---james-webadmin-url http://james:8000
-```
+## Operational attributes
 
-The James plugin listens to `onLdapMailChange` and `onLdapQuotaChange` hooks and automatically updates the James mail server.
-
-### Custom Integration Plugin
-
-Create a custom plugin that reacts to changes:
+A search returns no operational attribute unless asked by name, so neither
+side holds `pwdAccountLockedTime` or its kind by default, and a write changing
+only such an attribute fires no hook. A plugin that follows some declares them:
 
 ```typescript
-import DmPlugin from '../abstract/plugin';
-import { Hooks } from '../hooks';
-
-export default class CustomSync extends DmPlugin {
-  name = 'customSync';
-
-  dependencies = {
-    onChange: 'core/ldap/onChange',
-  };
-
-  hooks: Hooks = {
-    onLdapMailChange: async (dn, oldMail, newMail) => {
-      this.logger.info(`Mail changed: ${oldMail} → ${newMail}`);
-
-      try {
-        await fetch('https://api.example.com/update-email', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ dn, oldMail, newMail }),
-        });
-      } catch (err) {
-        this.logger.error(`Failed to sync mail change: ${err}`);
-      }
-    },
-  };
-}
+followedOperationalAttributes = ['pwdAccountLockedTime'];
 ```
 
-## Change Detection
+The entry is then read with `*` and every attribute a loaded plugin declares.
 
-### Replace Operations
+## What counts as a change
 
-```javascript
-// Before: mail = "old@example.com"
-{
-  replace: {
-    mail: 'new@example.com';
-  }
-}
-// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", "old@example.com", "new@example.com")
-```
-
-### Add Operations
+Values are compared as sets: a single value and a one-element array are equal,
+and so are two orderings of the same values. A write that leaves every value
+as it was, such as a `replace` with the current value, fires no hook.
 
-```javascript
-// Before: mail = undefined
-{
-  add: {
-    mail: 'new@example.com';
-  }
-}
-// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", null, "new@example.com")
-```
+## Timing and errors
 
-### Delete Operations
-
-```javascript
-// Before: mail = "old@example.com"
-{ delete: ["mail"] }
-// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", "old@example.com", null)
-```
-
-## Performance Considerations
-
-### Hook Execution
-
-- Hooks run **synchronously** within the modify operation
-- Slow hooks delay the LDAP response
-- Consider async operations with fire-and-forget for non-critical updates
-
-### Optimization Tips
-
-1. **Keep hooks fast**: Defer heavy work to background jobs
-2. **Use error handling**: Don't let hook failures block LDAP operations
-3. **Batch updates**: If possible, batch multiple hook calls
-4. **Cache external state**: Avoid redundant external API calls
-
-## Error Handling
-
-Hooks can throw errors to abort the LDAP modification:
-
-```javascript
-hooks: {
-  onLdapMailChange: async (dn, oldMail, newMail) => {
-    // Validate mail domain
-    if (!newMail.endsWith('@company.com')) {
-      throw new Error('Mail must be @company.com domain');
-    }
-
-    // Update mail server
-    try {
-      await mailServer.renameAccount(oldMail, newMail);
-    } catch (err) {
-      throw new Error(`Mail server update failed: ${err.message}`);
-    }
-  };
-}
-```
-
-If the hook throws, the LDAP modification is rolled back (if supported by LDAP server).
-
-## Debugging
-
-Enable debug logging to see change detection:
-
-```bash
---log-level debug
-```
-
-Output:
-
-```
-[debug] Detected mail change for uid=jdoe,ou=users,dc=example,dc=com: old@domain.com → new@domain.com
-[debug] Triggering onLdapMailChange hook
-[info] onLdapMailChange: Mail account renamed successfully
-```
+Hooks run after the directory has accepted the write, and the API answers
+without waiting for them. A hook that throws is logged; the write stays.
 
 ## Limitations
 
-1. **Only monitors modify operations**: Does not detect changes from direct LDAP clients
-2. **Requires old value lookup**: Fetches entry before modification for comparison
-3. **Single-valued attributes**: Best suited for single-valued attributes like mail
-4. **Synchronous execution**: Hooks block the LDAP response
-
-## See Also
-
-- [Twake James Plugin](twakeJames.md) - Mail server integration using onChange
-- [ldapFlatGeneric.md](ldapFlatGeneric.md) - Generic LDAP entity management
-- [Hooks Documentation](../src/hooks.ts) - All available hooks
+- Only writes made through LDAP-Rest are seen; a direct LDAP client's are not.
+- Entries moved by the [trash](trash.md) plugin are not seen, nor the entries
+  under a renamed container, which move with it.
+- Each write reads the entry before and after it: one search on each side.

package/docs/usage/troubleshooting.md

@@ -89,15 +89,7 @@ DM_LOG_LEVEL=debug ldap-rest
 
 ## Testing
 
-Run the test suite:
-
-```bash
-# All tests
-source ~/.test-env && npm run test:dev
-
-# Single file
-source ~/.test-env && npm run test:one test/path/to/file.test.ts
-```
+See [Tests and checks](../../CONTRIBUTING.md#tests-and-checks).
 
 ## Support
 

package/docs/usage/upgrading.md

@@ -4,6 +4,58 @@ What to check before deploying, newest first. Only releases that need a
 decision or a configuration change appear here; see the
 [CHANGELOG](../../CHANGELOG.md) for everything else.
 
+## To 0.10.0
+
+### LDAP base is now required
+
+**Who is affected:** a deployment that starts `ldap-rest` without
+`--ldap-base` (or `DM_LDAP_BASE`).
+
+The server refuses to start without it. It used to take the second RDN of
+`--ldap-dn` — `dc=example` for `cn=admin,dc=example,dc=com` — so subtree
+searches failed or found nothing. Set `--ldap-base` to the DN under which
+the entries are searched.
+
+### Group rules now apply
+
+**Who is affected:** a deployment whose `--authz-per-branch-config` declares
+a `groups` section.
+
+That section granted nothing: permissions came from `users` and `default`
+alone. A member of a configured group now also gets what its rule grants.
+**Check the `groups` rules before upgrading.**
+
+### An identity naming several entries is refused
+
+**Who is affected:** a directory where the same `uid` appears twice — one
+without a `unique` overlay, or one where a homonym was left in the trash
+while the uid was reused.
+
+`authzLinid1` refuses every request of such a caller with a `403`.
+`authzPerBranch` keeps the uid's `users` rules and withholds the `groups`
+rules. Both log a warning naming the identity and the number of entries it
+matched.
+
+**Check your directory before upgrading:**
+
+```bash
+ldapsearch -x -b "<base>" "(uid=<uid>)" dn
+```
+
+must answer one entry. Where it answers two, remove the duplicate — the
+trash included — or restore the uniqueness the `unique` overlay enforces.
+
+### `onLdapChange` gives full values
+
+**Who is affected:** plugins listening to `onLdapChange` that read the values
+of an `add`, or of a `delete` naming values, as the values added or removed.
+
+Each attribute now maps to all its values before and after the write. Adding
+`c` to `member: [a, b]` gave `[null, [c]]` and gives `[[a, b], [a, b, c]]`.
+Compute what was added or removed as the difference of the two sides, as the
+plugins shipped with LDAP-Rest do. A `replace` with the current value no
+longer fires the hook.
+
 ## To 0.9.0
 
 ### Two authorization plugins judging the same requests no longer start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"