ldap-rest 0.8.2 → 0.10.0

package/dist/src/plugins/bcl.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @module plugins/bcl
+ *
+ * Back-Channel Logout: what a provider tells us is dead, and what we do with
+ * it on the next request.
+ *
+ * Nothing here stores a session. `core/auth/openidconnect` keeps that in its
+ * cookie; a logout token only leaves a **tombstone** saying that one `sid`, or
+ * every session of one `sub`, is dead, and each request asks whether such a
+ * mark exists. Recording only what is dead is what keeps the sessions
+ * stateless and the storage small.
+ *
+ * Where the marks live is `core/storage`'s business, not this plugin's. What
+ * stays here is the policy: which keys a token kills, how long a mark is
+ * kept, and what a login forgets.
+ *
+ * @group Plugins
+ */
+import DmPlugin from '../abstract/plugin';
+import type { DM } from '../bin';
+import type { OidcLogoutToken, OidcSessionClaims } from '../hooks';
+export default class Bcl extends DmPlugin {
+    name: string;
+    dependencies: {
+        storage: string;
+    };
+    private storage?;
+    /** How long a tombstone is kept, in milliseconds. */
+    private retention;
+    constructor(server: DM);
+    /**
+     * Take hold of the store.
+     *
+     * Deliberately not the constructor. A plugin is built before
+     * `registerPlugin` reads its `dependencies` and loads what they name, so a
+     * constructor asking for the store answers for the order of two `--plugin`
+     * arguments rather than for the configuration: `core/bcl` listed first
+     * would be refused for a storage that is right there, and the declaration
+     * above — the thing meant to make order irrelevant — would have loaded it
+     * a moment later. `api()` runs after that loop, which is where
+     * `requirePlugin`'s own promise starts holding.
+     */
+    api(): void;
+    /**
+     * The store, once `api()` has taken hold of it.
+     *
+     * `registerPlugin` calls `api()` before it subscribes anything, so a hook
+     * running without one means a plugin built by hand and never registered —
+     * a test, in practice. Saying so beats reading `undefined` as "nothing is
+     * recorded", which is the fail-open this plugin exists to prevent.
+     */
+    private get store();
+    /**
+     * The keys a token kills.
+     *
+     * A provider sends `sid`, or `sub`, or both: `sid` ends one session, `sub`
+     * ends every session of that person.
+     */
+    private static keys;
+    hooks: {
+        oidclogouttoken: (token: OidcLogoutToken) => Promise<void>;
+        oidclogin: (claims: OidcSessionClaims) => Promise<void>;
+        oidcsessionvalid: ([claims, valid]: [OidcSessionClaims, boolean]) => Promise<[OidcSessionClaims, boolean]>;
+    };
+}

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

@@ -87,7 +87,9 @@ export default class LdapGroups extends DmPlugin {
     schema?: Schema;
     constructor(server: DM);
     /**
-     * Catch all deletion to remove deleted users from groups
+     * Remove deleted entries from groups once the delete has landed: a delete
+     * refused, failed or turned into something else by another plugin leaves
+     * the memberships alone.
      */
     hooks: Hooks;
     /**
@@ -123,14 +125,14 @@ export default class LdapGroups extends DmPlugin {
     /**
      * LDAP group methods
      */
-    addGroup(cn: string, members?: string[], additional?: AttributesList): Promise<boolean>;
+    addGroup(cn: string, members?: string[], additional?: AttributesList, req?: Request): Promise<boolean>;
     modifyGroup(cn: string, changes: {
         add?: AttributesList;
         replace?: AttributesList;
         delete?: string[] | AttributesList;
-    }): Promise<boolean>;
-    renameGroup(cn: string, newCn: string): Promise<boolean>;
-    deleteGroup(cn: string): Promise<boolean>;
+    }, req?: Request): Promise<boolean>;
+    renameGroup(cn: string, newCn: string, req?: Request): Promise<boolean>;
+    deleteGroup(cn: string, req?: Request): Promise<boolean>;
     addMember(cn: string, member: string | string[]): Promise<boolean>;
     deleteMember(cn: string, member: string): Promise<boolean>;
     deleteMemberFromAll(memberDn: string): Promise<void>;

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

@@ -139,8 +139,82 @@ export default class LdapOrganizations extends DmPlugin {
     getOrganisationTop(req?: Request): Promise<AttributesList | AttributesList[]>;
     getOrganisationByDn(dn: string, req?: Request): Promise<AttributesList>;
     getOrganisationSubnodes(dn: string, req?: Request): Promise<AttributesList[]>;
+    /** Nodes already warned about, so a crowded tree says it once per node. */
+    private sizeLimitWarned;
+    /** How many of them to remember. */
+    private static readonly SIZE_LIMIT_WARNED_MAX;
+    /**
+     * Say once per node what only the directory can fix.
+     *
+     * A console expanding a tree lists the same crowded node on every refresh,
+     * and a warning per listing buries the rest of the log while saying
+     * nothing new: the answer stays partial until someone raises the size
+     * limit. The first listing carries the message, the others go to `debug`.
+     *
+     * The set is bounded, so a directory with thousands of crowded nodes
+     * cannot grow it without end. Past the bound the message is written every
+     * time — the loud side of the trade rather than the silent one.
+     *
+     * @param key node the message is about
+     * @param message what to say
+     */
+    private warnSizeLimit;
+    /**
+     * The child organizations of a node, and what to do when the directory
+     * will not list them all.
+     *
+     * Every failure used to be read as "no children" (#179): the node's own
+     * children were searched without a limit, and a directory answering
+     * `sizeLimitExceeded` rather than a long list left the endpoint returning
+     * `200 []` with nothing above `debug` to say so. An empty tree is what a
+     * console then draws for a branch holding a thousand organizations.
+     *
+     * Three outcomes, and only one of them is emptiness:
+     *
+     *  - `noSuchObject` (32): nothing is there. An empty answer is the truth.
+     *  - `sizeLimitExceeded` (4): the answer was longer than the server's
+     *    limit. Measured against OpenLDAP 2.5, the paged control does not lift
+     *    it — `size.prtotal` bounds the whole search, so a paged walk ends on
+     *    the same refusal. What does change the answer is asking for a bounded
+     *    number: ldapts raises the refusal only when the request carried no
+     *    `sizeLimit` of its own, so a second, bounded search comes back with
+     *    entries where the first came back with an error. The answer then says
+     *    it is partial, through the `moreIndicator` row the attached entries
+     *    already use.
+     *  - anything else is a failure, and answering `[]` to a failure is how a
+     *    broken directory comes to look exactly like an empty one.
+     *
+     * The first search is paged for the directories where paging *is* what
+     * lifts the limit: Active Directory answers an unpaged search with at most
+     * `MaxPageSize` entries and expects the control for the rest.
+     *
+     * @param dn organization whose children are wanted
+     * @param filter what those children have to match
+     * @param cap how many to keep when the directory will not list them all
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns the children, followed by a `moreIndicator` row when the
+     *          directory refused to list them all
+     */
+    private childOrganizations;
+    /**
+     * The entries attached to an organization without being one.
+     *
+     * Capped at `cap`, with a `moreIndicator` row counting what was left out —
+     * the behaviour this endpoint already had, plus the refusal the children
+     * search just learned to survive: a directory that will not walk the whole
+     * link filter is told about rather than turned into an empty list.
+     *
+     * @param baseDn branch the attached entries live in
+     * @param filter what links them to the organization
+     * @param cap how many to return
+     * @param dn organization they are attached to, for the indicator's DN
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns the entries, followed by a `moreIndicator` row when some were
+     *          left out
+     */
+    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`,
@@ -167,8 +241,23 @@ export default class LdapOrganizations extends DmPlugin {
     moveOrganization(dn: string, targetOrgDn: string, req?: Request): Promise<{
         newDn: string;
     }>;
-    deleteOrganization(dn: string): Promise<boolean>;
-    searchOrganisationSubnodes(dn: string, query: string): Promise<AttributesList[]>;
+    deleteOrganization(dn: string, req?: Request): Promise<boolean>;
+    /**
+     * The same two searches as `getOrganisationSubnodes`, narrowed by a query.
+     *
+     * Both go through the helpers that classify a failure rather than reading
+     * every one of them as emptiness (#179), and both now carry the request:
+     * they ran without one, and an authorization plugin skips its check when
+     * there is none — the same gap the flat routes had until 0.8.2. The
+     * attached entries are capped like the other endpoint's, since an answer
+     * the directory refuses to finish is what this is about.
+     *
+     * @param dn organization to search under
+     * @param query what to look for in a name, a description or an identity
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns matching organizations then matching attached entries
+     */
+    searchOrganisationSubnodes(dn: string, query: string, req?: Request): Promise<AttributesList[]>;
     /**
      * Provide configuration for config API
      */

package/dist/src/plugins/scim/baseResolver.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from '../../config/args';
-import type { DmRequest } from '../../lib/auth/base';
+import { type DmRequest } from '../../lib/auth/base';
 export interface BaseMapEntry {
     userBase?: string;
     groupBase?: string;
@@ -14,6 +14,8 @@ export declare class BaseResolver {
     private readonly userBaseHeader;
     private readonly groupBaseHeader;
     private readonly headerRoot;
+    /** Kept so a base is keyed on whatever `--authz-identity` names. */
+    private readonly config;
     constructor(config: Config);
     private applyTemplate;
     /** Read a request header by name, tolerating Express req or a plain object. */

package/dist/src/plugins/scim/errors.d.ts

@@ -6,6 +6,8 @@
  */
 import type { Request, Response, NextFunction, RequestHandler } from 'express';
 import { HttpError } from '../../lib/errors';
+import { extractLdapCode } from '../../lib/ldapCodes';
+export { extractLdapCode };
 import { type ScimErrorResponse, type ScimErrorType } from './types';
 export declare const SCIM_CONTENT_TYPE = "application/scim+json";
 export declare class ScimError extends HttpError {
@@ -22,16 +24,6 @@ export declare const scimUniqueness: (detail?: string) => ScimError;
 export declare const scimTooMany: (detail?: string) => ScimError;
 export declare const scimNotFound: (detail?: string) => ScimError;
 export declare function writeScimError(res: Response, status: number, detail: string, scimType?: ScimErrorType): void;
-/**
- * Extract an LDAP numeric error code from a thrown ldapts error.
- *
- * `.code` first: ldapts sets it, and `ldapActions` now carries it across its
- * own wrapping rather than reducing the failure to a sentence. The message
- * patterns below stay as a fallback for the paths that still throw a bare
- * `Error` — they are why a driver that reworded its messages could quietly
- * turn a 400 into a 500, so they are the last resort, not the first.
- */
-export declare function extractLdapCode(err: unknown): number | undefined;
 /**
  * Turn any thrown thing into the SCIM error body it deserves.
  *

package/dist/src/plugins/storage/file.d.ts

@@ -0,0 +1,19 @@
+import type winston from 'winston';
+import Store, { type StoredRecord } from '../../lib/storage/store';
+export default class FileStore extends Store {
+    name: string;
+    private dir;
+    /** How long a temporary file must sit before it counts as abandoned. */
+    private abandonedAfter;
+    constructor(logger: winston.Logger, dir: string, abandonedAfterSeconds: number);
+    /** The directory is created on demand, readable by this user alone. */
+    ready(): Promise<void>;
+    private path;
+    /** `<deadline> <key>\n<value>` — the deadline first, so a short read still has it. */
+    private static encode;
+    private static decode;
+    protected load(key: string): Promise<StoredRecord | null>;
+    protected save(key: string, record: StoredRecord): Promise<void>;
+    protected drop(key: string): Promise<void>;
+    sweep(): Promise<number>;
+}

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

@@ -0,0 +1,17 @@
+import Store, { type StoredRecord } from '../../lib/storage/store';
+import type { DM } from '../../bin';
+export default class LdapStore extends Store {
+    name: string;
+    private server;
+    private base;
+    private objectClass;
+    constructor(server: DM, base: string, objectClass: string);
+    private dn;
+    /** `<deadline> <key>\n<value>`, the deadline first as in the file store. */
+    private static encode;
+    private static decode;
+    protected load(key: string): Promise<StoredRecord | null>;
+    protected save(key: string, record: StoredRecord): Promise<void>;
+    protected drop(key: string): Promise<void>;
+    sweep(): Promise<number>;
+}

package/dist/src/plugins/storage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module plugins/storage
+ *
+ * Keyed storage, for whoever needs to keep something with a deadline.
+ *
+ * One plugin, one backend, chosen by `--storage-backend`. Consumers ask this
+ * one for its store and work through a single interface; where the records
+ * actually live is a deployment decision, not theirs.
+ *
+ * Having exactly one is the point. The alternative — each consumer loading
+ * the backend it likes — puts the same record in two places, and makes
+ * whichever plugin was registered first decide what happens when one of them
+ * is unwell. Registration order is invisible in a configuration, which is a
+ * poor place to keep a behaviour.
+ *
+ * A consumer reaches it with `requirePlugin('storage')` and works through
+ * `store`; it should not index `loadedPlugins` itself. And one that makes a
+ * security decision must not read "no storage" as "nothing to check":
+ * `requirePlugin` answers null and warns once, which is right for an optional
+ * feature and wrong for, say, a logout check — such a consumer refuses to
+ * load instead.
+ *
+ * What a consumer must not expect of this layer: it does not decide how long
+ * anything lives. A deadline comes in with the record, because retention is
+ * the policy of whoever wrote it — the moment a backend decides for itself,
+ * two of them can disagree about when the same record died.
+ *
+ * @group Plugins
+ */
+import DmPlugin from '../abstract/plugin';
+import type { DM } from '../bin';
+import type Store from '../lib/storage/store';
+export default class Storage extends DmPlugin {
+    name: string;
+    store: Store;
+    constructor(server: DM);
+    /**
+     * Release the single-instance hold.
+     *
+     * For a test building several servers in one process; a running one has no
+     * reason to call it.
+     */
+    static release(instance: Storage): void;
+}

package/docs/plugin-development/README.md

@@ -475,7 +475,18 @@ The `this.server.ldap` object provides access to all LDAP operations:
 > `forRequest()` returns a `RequestBoundLdap`, whose methods have no request
 > parameter at all — the omission stops being expressible. Use the unbound
 > methods only for work that genuinely belongs to no request, such as startup
-> or scheduled tasks, where passing nothing is the deliberate answer.
+> or scheduled tasks, where passing nothing is the deliberate answer — and
+> say so by reaching for them through `ldap.system`:
+>
+> ```typescript
+> await this.server.ldap.system.search({ scope: 'base' }, dn);
+> ```
+>
+> It is the same object, and that is the point: `ldap.system.search(…)` reads
+> as a decision where `ldap.search(…)` reads as a forgotten argument. Some
+> reads are the server's by nature — a uniqueness check has to see a whole
+> branch, and a reference to an entry the caller cannot read is still a valid
+> reference — and those are the ones it names.
 
 #### Search
 
@@ -1272,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/dependencies.md

@@ -76,6 +76,16 @@ dependencies = {
 - **Consumes Hooks**: None
 - **Notes**: LinID 1.x authorization integration
 
+#### `bcl` (core/bcl)
+
+- **Dependencies**: `core/storage` — **required**: a logout check with
+  nowhere to record what died would leave every session outliving the logout
+  that closed it, so the plugin refuses to start
+- **Provides Hooks**: None
+- **Consumes Hooks**: `oidclogouttoken`, `oidclogin`, `oidcsessionvalid`
+- **Notes**: Back-Channel Logout. Records only the sessions a provider
+  declared dead; needs `core/auth/openidconnect` to raise those hooks
+
 ### LDAP Core Plugins
 
 #### `onLdapChange` (core/ldap/onChange)
@@ -238,6 +248,15 @@ dependencies = {
 - **Consumes Hooks**: None
 - **Notes**: HTTP request logging
 
+#### `storage` (core/storage)
+
+- **Dependencies**: None (the `ldap` backend uses the server's connection)
+- **Provides Hooks**: None
+- **Consumes Hooks**: None
+- **Notes**: Keyed storage with a deadline. Only one instance may be loaded —
+  a second one is refused rather than leaving registration order to decide
+  which answers
+
 #### `configApi` (core/configApi)
 
 - **Dependencies**: None (reads configuration from other loaded plugins)
@@ -531,24 +550,30 @@ graph TB
 - `static` - Static files
 - `weblogs` - Logging
 - `configApi` - Configuration API
+- `storage` - Keyed storage. Written anywhere in the configuration, but
+  loaded before the others: its consumers have to find it registered, so it
+  is in the priority list
 
 ## Plugin Priority System
 
-LDAP-Rest uses a priority system defined in `src/plugins/priority.json`:
-
-```json
-[
-  "core/auth/crowdsec",
-  "core/auth/rateLimit",
-  "core/auth/token",
-  "core/auth/llng",
-  "core/auth/openidconnect",
-  "core/auth/authzPerBranch",
-  "core/auth/authzLinid1"
-]
-```
-
-Plugins in this list load before others, ensuring security plugins run first.
+LDAP-Rest uses a priority system defined in
+[`src/plugins/priority.json`](../../src/plugins/priority.json), which is the
+list itself — copying it here is how this section came to name two plugins
+the file does not and to omit four it does.
+
+Plugins in that list are loaded one at a time, in its order, before every
+other plugin is loaded in parallel. Two reasons put a plugin there: a
+security plugin whose middleware must sit ahead of the routes it guards, and
+a plugin others depend on, which has to be registered before the batch its
+consumers land in — `core/storage` is there for the second reason.
+
+The list matches on the **module**, so a named instance
+(`core/auth/token:authAdmins:{…}`) keeps its rank, and every instance of a
+priority module is loaded in that first pass, in configuration order. It
+used to be matched on the whole `--plugin` string, which sent exactly the
+configurations that carry per-instance options into the parallel batch —
+`core/auth/trustedProxy` named that way registered after the routes it
+guards.
 
 ## Hook Execution Order
 

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