ldap-rest 0.9.0 → 0.11.0

package/dist/src/plugins/ldap/onChange.d.ts

@@ -1,33 +1,42 @@
 /**
  * @module core/onLdapChange
- * Check for ldap modify events and generate hooks:
- *  - onLdapChange
- *  - onLdapMailChange
+ * Publish the state of an entry before and after each write
+ * (onLdapEntryChange), and the hooks derived from it: onLdapChange,
+ * onLdapMailChange…
  * @author Xavier Guimard <xguimard@linagora.com>
  */
 import { Entry } from 'ldapts';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { Hooks } from '../../hooks';
 import type { AttributeValue } from '../../lib/ldapActions';
+import type { ChangeContext } from '../../lib/changeContext';
 export type ChangesToNotify = Record<string, [
     AttributeValue | null,
     AttributeValue | null
 ]>;
+/**
+ * The attributes whose values differ between two states of an entry. Values
+ * are compared as sets, so a single value and a one-element array are equal,
+ * and so are two orderings of the same values.
+ */
+export declare function diffEntries(before: Entry | null, after: Entry | null): ChangesToNotify;
 declare class OnLdapChange extends DmPlugin {
     name: string;
     roles: Role[];
     stack: Record<number, Entry>;
     pendingDeletions: Map<string, Entry>;
+    pendingRenames: Map<string, Entry>;
     hooks: Hooks;
-    notify(dn: string, changes: ChangesToNotify): void;
+    read(dn: string): Promise<Entry | undefined>;
+    publish(dn: string, before: Entry | null, after: Entry | null, context?: ChangeContext): void;
+    notify(dn: string, changes: ChangesToNotify, before: Entry | null, after: Entry | null): void;
     notifyAttributeChange(attribute: string, hookName: keyof Hooks, dn: string, changes: ChangesToNotify, stringOnly?: boolean): void;
-    notifyAttributeChangeWithMail(attribute: string, hookName: keyof Hooks, dn: string, changes: ChangesToNotify): Promise<void>;
+    notifyAttributeChangeWithMail(attribute: string, hookName: keyof Hooks, dn: string, changes: ChangesToNotify, after: Entry | null): void;
     /**
      * Reconstruct display name from cn, givenName, and sn attributes
-     * @param changes - The changes object
-     * @param index - 0 for old value, 1 for new value
+     * @param entry - The entry, before or after the change
      * @returns The reconstructed display name or null
      */
-    reconstructDisplayName(changes: ChangesToNotify, index: 0 | 1): string | null;
+    reconstructDisplayName(entry: Entry | null): string | null;
 }
 export default OnLdapChange;

package/dist/src/plugins/ldap/organizations.d.ts

@@ -214,7 +214,7 @@ export default class LdapOrganizations extends DmPlugin {
      */
     private linkedEntities;
     addOrganization(dn: string, entry: AttributesList, req?: Request): Promise<boolean>;
-    modifyOrganization(dn: string, changes: ModifyRequest): Promise<boolean>;
+    modifyOrganization(dn: string, changes: ModifyRequest, req?: Request): Promise<boolean>;
     validateNewOrganization(dn: string, entry: AttributesList): Promise<boolean>;
     /**
      * Build the rejection message for a value that failed its schema `test`,
@@ -241,7 +241,7 @@ export default class LdapOrganizations extends DmPlugin {
     moveOrganization(dn: string, targetOrgDn: string, req?: Request): Promise<{
         newDn: string;
     }>;
-    deleteOrganization(dn: string): Promise<boolean>;
+    deleteOrganization(dn: string, req?: Request): Promise<boolean>;
     /**
      * The same two searches as `getOrganisationSubnodes`, narrowed by a query.
      *

package/docs/plugin-development/README.md

@@ -1283,24 +1283,7 @@ describe('NotificationPlugin', function () {
 
 ### Running Tests
 
-```bash
-# Set up test environment
-cat > ~/.test-env <<EOF
-export DM_LDAP_URL="ldap://localhost:389"
-export DM_LDAP_DN="cn=admin,dc=example,dc=com"
-export DM_LDAP_PWD="admin"
-export DM_LDAP_BASE="dc=example,dc=com"
-EOF
-
-# Run all tests
-source ~/.test-env && npm test
-
-# Run specific test file
-source ~/.test-env && npm run test:one test/plugins/notification/webhook.test.ts
-
-# Run tests in watch mode
-source ~/.test-env && npm run test:dev
-```
+See [Tests and checks](../../CONTRIBUTING.md#tests-and-checks).
 
 ### Test Best Practices
 

package/docs/plugin-development/hooks.md

@@ -16,3 +16,9 @@ Typescript definitions into [hooks.ts](./src/hooks.ts)
 - **ldapmodifyrequest**: called before any ldapmodify
 - **ldapdeleterequest**: called before any ldapdelete
 - **ldaprenamerequest**: called before any ldap rename/modifyDN operation
+
+## [onChange](../usage/plugins/ldap/on-change.md) hooks
+
+- **onLdapEntryChange**: called after any write, with the entry before and
+  after it, and who made it
+- **onLdapChange**, **onLdapMailChange**…: derived from it

package/docs/plugin-development/testing.md

@@ -76,23 +76,7 @@ Loading initial LDIF from .../base-structure.ldif...
 
 ### Running Tests
 
-**Using embedded LDAP (no setup required):**
-
-```bash
-npm test
-npm run test:one test/plugins/ldap/flatGeneric.test.ts
-```
-
-**Using external LDAP:**
-
-```bash
-export DM_LDAP_URL=ldap://localhost:389
-export DM_LDAP_DN=cn=admin,dc=example,dc=com
-export DM_LDAP_PWD=secret
-export DM_LDAP_BASE=dc=example,dc=com
-
-npm test
-```
+See [Tests and checks](../../CONTRIBUTING.md#tests-and-checks).
 
 ### In CI/CD
 

package/docs/usage/configuration.md

@@ -25,6 +25,7 @@ All LDAP-Rest configuration options.
     - [core/auth/hmac](#coreauthhmac)
     - [core/auth/llng](#coreauthllng)
     - [core/auth/openidconnect](#coreauthopenidconnect)
+    - [core/auth/fake](#coreauthfake)
     - [core/bcl](#corebcl)
   - [Authorization Plugins](#authorization-plugins)
     - [Common to every authorization plugin](#common-to-every-authorization-plugin)
@@ -101,7 +102,7 @@ export DM_PLUGINS="core/auth/token,core/ldap/flatGeneric,core/ldap/groups"
 | `--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-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches (required)             |
 | `--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 |
@@ -238,6 +239,14 @@ Empty means the plugin guards every path. Scoping several instances to different
 | -------------- | --------------- | ---------------- | ------- | --------------------- |
 | `--auth-token` | `--auth-tokens` | `DM_AUTH_TOKENS` | `[]`    | Authentication tokens |
 
+#### `core/auth/fake`
+
+| CLI                | Env                 | Default | Description                                    |
+| ------------------ | ------------------- | ------- | ---------------------------------------------- |
+| `--auth-fake-user` | `DM_AUTH_FAKE_USER` |         | Identity every request is served as (required) |
+
+Development only, refused with `NODE_ENV=production` — see [Fake Authentication](plugins/auth/fake.md).
+
 #### `core/auth/totp`
 
 | CLI                  | Plural         | Env                   | Default | Description                      |
@@ -324,11 +333,11 @@ whichever of the two names it selects. A value other than `req.user` or
 
 #### `core/auth/authzPerBranch`
 
-| CLI                               | Env                                | Default                                          | Description                                                                                                                                                                   |
-| --------------------------------- | ---------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--authz-per-branch-config`       | `DM_AUTHZ_PER_BRANCH_CONFIG`       | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                   |
-| `--authz-per-branch-cache-ttl`    | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`    | `60`                                             | Cache TTL (seconds)                                                                                                                                                           |
-| `--authz-filter-attached-entries` | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES` | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch` and `authzLinid1`; does nothing under `authzDynamic`. |
+| CLI                               | Env                                | Default                                          | Description                                                                                                                                                                                |
+| --------------------------------- | ---------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--authz-per-branch-config`       | `DM_AUTHZ_PER_BRANCH_CONFIG`       | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                                |
+| `--authz-per-branch-cache-ttl`    | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`    | `60`                                             | Cache TTL (seconds)                                                                                                                                                                        |
+| `--authz-filter-attached-entries` | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES` | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch`; always on under `authzLinid1`; does nothing under `authzDynamic`. |
 
 #### `core/auth/authzScope`
 

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

@@ -11,6 +11,7 @@ LDAP-Rest provides multiple authentication plugins to secure API access. These p
 | [HMAC](hmac.md)           | `core/auth/hmac`          | HMAC-SHA256 request signing for backend services |
 | [LemonLDAP::NG](llng.md)  | `core/auth/llng`          | Integration with LemonLDAP::NG SSO               |
 | [OpenID Connect](oidc.md) | `core/auth/openidconnect` | OAuth 2.0 / OpenID Connect authentication        |
+| [Fake](fake.md)           | `core/auth/fake`          | Development only: a fixed identity, no login     |
 
 ## What a rule is keyed on
 
@@ -25,6 +26,7 @@ of what a caller is called. Every one of them publishes the caller twice:
 | `core/auth/llng`          | LLNG's `whatToTrace`                | `--llng-username-header`, or the same    |
 | `core/auth/openidconnect` | the OIDC `sub`                      | `--oidc-username-claim` (default: `sub`) |
 | `core/auth/authzDynamic`  | the token's tenant                  | the same                                 |
+| `core/auth/fake`          | `--auth-fake-user`                  | the same                                 |
 
 `req.user` is this server's identifier for the caller; `req.userName` is the
 caller under a name a person would use. `--authz-identity` says which one is

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

@@ -48,6 +48,24 @@ twakeDepartmentLink: ou=HR,ou=organization,dc=example,dc=com
 
 The HR admin (listed in `ou=HR`'s `twakeLocalAdminLink`) can manage John even though he's in `ou=users` because his `twakeDepartmentLink` points to the HR organization.
 
+### What an administrator reads
+
+`authzLinid1` always judges an attached entry this way, as
+`--authz-filter-attached-entries` does for `authzPerBranch`, whatever that
+option says: judged by its parent instead, an account in a flat `ou=users`
+belongs to nobody's branch, and no administrator could list or change one.
+
+- Listings of accounts and groups drop the entries attached to an
+  organization outside the caller's branches. A single read of one answers
+  `404`.
+- Entries attached to nothing — the organizations, the nomenclature values, a
+  group or an account with no `twakeDepartmentLink` — are readable by every
+  administrator: the organization tree is reference data. Writes to them are
+  judged on their parent. The tree a console draws still starts at the
+  caller's own branches: see [getOrganisationTop Hook](#getorganisationtop-hook).
+- A caller named in no `twakeLocalAdminLink` is refused every read (`403`)
+  but the top organization's own entry, which `organizations/top` answers.
+
 ## Configuration
 
 No configuration file needed - permissions are read from LDAP. Simply load the plugin:
@@ -75,19 +93,20 @@ works behind an authenticator that publishes what the directory calls a user:
 | `core/auth/openidconnect` | the OIDC `sub`                   | **no** — an opaque provider identifier |
 
 An identity that does not resolve is **refused** (403), and the refusal is
-logged with the plugin's name. Until 0.9.0 it was let through instead, which
-made this pairing an open door rather than a misconfiguration; see
-[the note](../../upgrading.md#an-identity-that-does-not-resolve-is-refused)
-and `--authz-unresolved-user` for the transition.
+logged with the plugin's name; `--authz-unresolved-user` sets it otherwise
+([notes](../../upgrading.md#an-identity-that-does-not-resolve-is-refused)).
+An identity naming **several** entries is refused (403) whatever that
+option says, and a warning gives the number of entries. A lookup the
+directory fails fails the request and is not cached.
 
 Both answers are cached for the plugin's TTL (5 minutes), negatives
 included, so a mismatch does not turn every request into a directory search.
 The TTL cuts both ways: an identity added to the directory after being
 refused waits it out, and an administrator whose **own entry is renamed or
 moved** keeps resolving to the former DN — where no organization names them,
-so their own operations are refused. A rename or a delete performed through
-this server drops what was resolved; a change made directly in the directory
-waits out the TTL.
+so their own operations are refused. A rename, a move to the trash or a
+delete performed through this server drops what was resolved; a change made
+directly in the directory waits out the TTL.
 
 `GET /api/v1/authz/scope` resolves the identity outside that cache, so
 during such a window it can describe a scope the hooks no longer grant.
@@ -178,8 +197,9 @@ Intercepts all LDAP search operations:
 2. Resolves user's DN from username
 3. Allows base scope searches on top organization (for navigation)
 4. Allows searches for `twakeLocalAdminLink` (for permission refresh)
-5. Verifies user has read permission for search base
-6. Throws error if access denied
+5. Refuses a caller who administers no branch; lets the others search, and
+   drops from the answer the entries attached outside their branches
+   (`ldapsearchfilter`)
 
 **Special allowances:**
 
@@ -460,31 +480,6 @@ User jdoe not found in LDAP
 
 3. Verify authentication plugin sets `req.user` correctly
 
-### Problem: Cannot Search Top Organization
-
-**Symptoms:**
-
-```json
-{
-  "error": "User admin does not have read permission for branch ou=organization,dc=example,dc=com"
-}
-```
-
-**Solutions:**
-
-This is expected behavior - users can only see organizations they manage. To grant access to top organization:
-
-```bash
-ldapsearch -x -b "ou=organization,dc=example,dc=com" -s base "(objectClass=*)"
-# Modify to add user:
-ldapmodify <<EOF
-dn: ou=organization,dc=example,dc=com
-changetype: modify
-add: twakeLocalAdminLink
-twakeLocalAdminLink: uid=admin,ou=users,dc=example,dc=com
-EOF
-```
-
 ## Integration Examples
 
 ### With Token Authentication

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/auth/fake.md

@@ -0,0 +1,28 @@
+# Fake Authentication
+
+For development only: every request is served as the identity given on the
+command line, without asking for anything. Restarting with another
+`--auth-fake-user` shows an interface as another administrator sees it.
+
+```bash
+npx ldap-rest \
+  --plugin core/auth/fake --auth-fake-user alice \
+  --plugin core/auth/authzLinid1 \
+  ...
+```
+
+**Environment Variable:** `DM_AUTH_FAKE_USER=alice`
+
+The identity goes to `req.user` and `req.userName` alike, so the
+authorization plugins judge it as they would the same login coming from a
+real authenticator.
+
+## Safeguards
+
+- The server refuses to start when `NODE_ENV` is `production`, as it is in
+  the Docker image.
+- It refuses to start without `--auth-fake-user`.
+- A warning naming the identity is logged at every start.
+
+Loaded without an authorization plugin, it grants everything to anyone who
+reaches the port. Listen on a local address only.