ldap-rest 0.9.0 → 0.11.0

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,99 @@ 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.11.0
+
+### Group reads are judged
+
+**Who is affected:** a deployment loading `core/ldap/groups` with an
+authorization plugin.
+
+Listing the groups and reading one went to the directory without the
+request, so no authorization plugin saw them: any authenticated caller read
+every group with its members. They are judged like any other read now.
+Under `core/auth/authzPerBranch` without `--authz-filter-attached-entries`,
+that means a `read` grant on the group base (`ou=groups`, or
+`--ldap-group-base`): **a caller without one is answered `403`** where the
+list used to come back.
+
+### authzLinid1 judges accounts and groups by their organization
+
+**Who is affected:** every deployment using `core/auth/authzLinid1`.
+
+It now works as with `--authz-filter-attached-entries`, whatever the option
+says. Without it, a flat `ou=users` was nobody's branch: no administrator
+could list or change an account.
+
+- An administrator lists the accounts and groups attached to their branches,
+  and those attached to none.
+- **The organization tree is readable by every administrator**, not only their
+  own branches: an organization is reference data. `organizations/top` still
+  answers their own branches, so a console starts there. Writes to the tree
+  are judged as before.
+- **A caller named in no `twakeLocalAdminLink` is refused every read** but the
+  top organization's own entry.
+- An account stored under the organization tree without a
+  `twakeDepartmentLink` becomes readable by every administrator. **Where
+  accounts sit under the tree, give them their link before upgrading.** This
+  lists the accounts that have none, under `twakeDepartmentLink: missing`:
+
+  ```bash
+  npm run audit:directory -- --schema static/schemas/twake/users.json \
+    --base ou=users,<base> --filter '(!(twakeDepartmentLink=*))'
+  ```
+
+## 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.11.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -64,6 +64,10 @@
       "types": "./dist/src/plugins/auth/crowdsec.d.ts",
       "import": "./dist/plugins/auth/crowdsec.js"
     },
+    "./plugin-auth-fake": {
+      "types": "./dist/src/plugins/auth/fake.d.ts",
+      "import": "./dist/plugins/auth/fake.js"
+    },
     "./plugin-auth-hmac": {
       "types": "./dist/src/plugins/auth/hmac.d.ts",
       "import": "./dist/plugins/auth/hmac.js"