ldap-rest 0.4.7 → 0.6.0

package/dist/src/lib/utils.d.ts

@@ -73,6 +73,8 @@ export declare function escapeDnValue(value: string): string;
  * unescapeDnValue('user\\+admin')
  * // => 'user+admin'
  * ```
+ *
+ * @throws BadRequestError if `value` is not a string
  */
 export declare function unescapeDnValue(value: string): string;
 /**
@@ -108,6 +110,8 @@ export declare function validateDnValue(value: string, fieldName: string): void;
  * parseDn('cn=Smith\\, John,ou=users,dc=example,dc=com')
  * // => ['cn=Smith\\, John', 'ou=users', 'dc=example', 'dc=com']
  * ```
+ *
+ * @throws BadRequestError if `dn` is not a string
  */
 export declare function parseDn(dn: string): string[];
 /**

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

@@ -0,0 +1,251 @@
+/**
+ * @module plugins/ldap/raw
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * Low-level LDAP browsing API (read-only).
+ *
+ * Where the other plugins expose business objects (users, groups,
+ * organizations), this one exposes the directory itself: the root DSE, the
+ * schema, and entries addressed by their DN. It is the server side of a
+ * phpLDAPadmin-like interface.
+ *
+ * Every directory access goes through `server.ldap`, so the authorization,
+ * trash and logging hooks apply exactly as they do for the high-level APIs.
+ * Root DSE and schema are directory metadata rather than user data and are
+ * read with the service account, so that a UI can render attribute names and
+ * types even when the caller is restricted to a branch.
+ */
+import type { Express, Request } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import { SchemaIndex, type LdapSchema } from '../../lib/ldapSchema';
+/**
+ * Shared OpenAPI schemas surfaced by this plugin. Picked up by
+ * scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * RawAttribute:
+ *   type: object
+ *   description: |
+ *     Values of a single attribute. When `binary` is true the values are
+ *     base64-encoded octets rather than text.
+ *   required: [values, binary]
+ *   properties:
+ *     values:
+ *       type: array
+ *       items: { type: string }
+ *       example: [Alice Smith]
+ *     binary: { type: boolean, example: false }
+ * RawEntry:
+ *   type: object
+ *   description: A directory entry with all its attributes, as stored.
+ *   required: [dn, attributes]
+ *   properties:
+ *     dn:
+ *       type: string
+ *       example: uid=alice,ou=users,dc=example,dc=com
+ *     attributes:
+ *       type: object
+ *       additionalProperties: { $ref: '#/components/schemas/RawAttribute' }
+ *   example:
+ *     dn: uid=alice,ou=users,dc=example,dc=com
+ *     attributes:
+ *       objectClass: { values: [top, inetOrgPerson], binary: false }
+ *       uid: { values: [alice], binary: false }
+ *       cn: { values: [Alice Smith], binary: false }
+ * RawChild:
+ *   type: object
+ *   description: Direct child of an entry, as needed to draw a tree node.
+ *   required: [dn, rdn, objectClass, hasChildren]
+ *   properties:
+ *     dn: { type: string, example: uid=alice,ou=users,dc=example,dc=com }
+ *     rdn: { type: string, example: uid=alice }
+ *     objectClass:
+ *       type: array
+ *       items: { type: string }
+ *       example: [top, inetOrgPerson]
+ *     hasChildren:
+ *       type: boolean
+ *       description: |
+ *         Whether the entry has at least one child. Only computed when the
+ *         `children` query parameter is set, otherwise always false.
+ *       example: false
+ */
+/** JSON representation of one attribute of an entry */
+export interface RawAttribute {
+    /** Values, base64-encoded when `binary` is true */
+    values: string[];
+    binary: boolean;
+}
+/** JSON representation of a directory entry */
+export interface RawEntry {
+    dn: string;
+    attributes: Record<string, RawAttribute>;
+}
+/** Direct child of an entry, as needed to draw a tree node */
+export interface RawChild {
+    dn: string;
+    rdn: string;
+    objectClass: string[];
+    hasChildren: boolean;
+}
+/** Direct children of an entry, with the truncation flag */
+export interface RawChildren {
+    children: RawChild[];
+    /** True when `ldap_raw_max_results` cut the listing short */
+    truncated: boolean;
+}
+/** Result of a raw search */
+export interface RawSearchResult {
+    entries: RawEntry[];
+    /** True when `ldap_raw_max_results` cut the result set short */
+    truncated: boolean;
+}
+declare const VALID_SCOPES: readonly ["base", "one", "sub"];
+type Scope = (typeof VALID_SCOPES)[number];
+export default class LdapRaw extends DmPlugin {
+    name: string;
+    roles: Role[];
+    /** Subtrees the API is allowed to expose */
+    bases: string[];
+    /** Attributes never returned, whatever the request (lowercase) */
+    hiddenAttributes: Set<string>;
+    /** True when credential attributes are served instead of being hidden */
+    showSecrets: boolean;
+    /** Maximum entries returned by a search or a children listing */
+    maxResults: number;
+    private schemaCacheTtl;
+    private schemaCache?;
+    private schemaPromise?;
+    constructor(server: DM);
+    /**
+     * Reject any DN outside the configured bases. Authorization plugins narrow
+     * access further; this is the coarse boundary of the API itself.
+     *
+     * @param dn DN to check
+     * @throws BadRequestError when the DN is empty
+     * @throws ForbiddenError when the DN is outside every configured base
+     */
+    checkDn(dn: string): void;
+    /**
+     * Reject a malformed LDAP filter before it reaches the directory. Parsing
+     * it here turns what would surface as an opaque server error into a 400
+     * naming the offending expression — a search box hands us whatever the
+     * user typed, and `gov` is a filter typo, not a server fault.
+     *
+     * @param filter filter to validate
+     * @throws BadRequestError when the filter cannot be parsed
+     */
+    checkFilter(filter: string): void;
+    /**
+     * Convert an ldapts entry into its JSON representation: values are always
+     * arrays and hidden attributes are dropped.
+     *
+     * ldapts hands back a `Buffer` for values it could not decode as UTF-8 and
+     * for the attribute types it knows to be binary; those are the ones that
+     * need base64. A hashed `userPassword` is valid UTF-8 and stays readable,
+     * which is what an administration UI wants to display.
+     *
+     * @param entry entry as returned by ldapts
+     * @returns JSON-serializable entry
+     */
+    formatEntry(entry: Record<string, unknown> & {
+        dn: string;
+    }): RawEntry;
+    /**
+     * Run a search and turn the directory's "no such object" result code (32)
+     * into a 404, instead of letting it surface as a server error.
+     *
+     * @param base search base
+     * @param options search options
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns the search result
+     * @throws NotFoundError when the base does not exist
+     */
+    private searchDirectory;
+    /**
+     * Read the root DSE: naming contexts, supported controls and extensions,
+     * and the DN of the subschema entry.
+     *
+     * @returns root DSE as a JSON entry (its `dn` is the empty string)
+     */
+    getRootDse(): Promise<RawEntry>;
+    /**
+     * Locate the subschema entry advertised by the root DSE, falling back to
+     * the conventional `cn=Subschema` when the server does not advertise one.
+     *
+     * @returns DN of the subschema entry
+     */
+    getSubschemaDn(): Promise<string>;
+    /**
+     * Fetch and parse the directory schema, with a cache: it is large and
+     * changes rarely. Concurrent callers share a single fetch.
+     *
+     * @returns indexed schema
+     */
+    getSchemaIndex(): Promise<SchemaIndex>;
+    /**
+     * Parsed schema, as served to clients.
+     *
+     * @returns object classes, attribute types, syntaxes and matching rules
+     */
+    getSchema(): Promise<LdapSchema>;
+    /**
+     * Read a single entry by DN, operational attributes included.
+     *
+     * @param dn DN of the entry
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns the entry
+     * @throws NotFoundError when the DN does not exist
+     */
+    getEntry(dn: string, req?: Request): Promise<RawEntry>;
+    /**
+     * List the direct children of an entry.
+     *
+     * @param dn DN of the parent entry
+     * @param withChildrenFlag when true, probe each child for its own children
+     *                         (one extra search per child)
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns children sorted by RDN, flagged as truncated when the branch
+     *          holds more than `--ldap-raw-max-results` entries
+     */
+    getChildren(dn: string, withChildrenFlag: boolean, req?: Request): Promise<RawChildren>;
+    /**
+     * Tell whether an entry has at least one child.
+     *
+     * @param dn DN of the entry
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns true when a child exists, false on error or empty result
+     */
+    hasChildren(dn: string, req?: Request): Promise<boolean>;
+    /**
+     * Run an arbitrary search below one of the exposed bases.
+     *
+     * @param options base, scope, filter and attributes of the search
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns matching entries, flagged as truncated when the limit was hit
+     */
+    search(options: {
+        base: string;
+        scope: Scope;
+        filter: string;
+        attributes?: string[];
+        limit?: number;
+    }, req?: Request): Promise<RawSearchResult>;
+    /**
+     * Parent DN of an entry, or null when it is one of the exposed bases.
+     *
+     * @param dn DN of the entry
+     * @returns parent DN, or null when the entry is a root of the API
+     */
+    parentOf(dn: string): string | null;
+    api(app: Express): void;
+    /**
+     * Expose the API settings to the config API, so a UI can adapt itself
+     * (bases to display, read-only mode).
+     *
+     * @returns public configuration of this plugin
+     */
+    getConfigApiData(): Record<string, unknown>;
+}
+export {};

package/dist/src/plugins/twake/appAccountsConsistency.d.ts

@@ -20,7 +20,9 @@
  *
  * When a user is deleted, all corresponding applicative accounts are also deleted.
  *
- * When a user's mail changes, all applicative accounts are updated with the new mail.
+ * When a user's mail changes, the principal account moves to the new address and
+ * the app accounts are deleted: every client has to be reconfigured against the
+ * new address anyway.
  */
 import DmPlugin from '../../abstract/plugin';
 import type { Role } from '../../abstract/plugin';
@@ -35,13 +37,49 @@ export default class AppAccountsConsistency extends DmPlugin {
     private mailAttr;
     private applicativeAccountBase;
     private operationalAttributes;
+    private copiedAttributes;
     constructor(server: DM);
     /**
-     * Check if an attribute should be excluded when copying LDAP entry attributes
+     * Check if an attribute should be excluded when recreating an existing
+     * applicative entry from its own current state.
+     *
+     * This is a denylist because the input is an entry we wrote ourselves: what
+     * has to go is what the directory generates and would refuse on an `add`,
+     * plus `userPassword` (an app account is reconfigured on every client after
+     * a mail change anyway, so its password is deliberately not carried over).
+     *
+     * Attributes coming from the *user* entry are chosen by
+     * {@link pickCopiedAttributes} instead — an allowlist, so that a new
+     * attribute on the user schema is never propagated by accident.
+     *
      * @param key - The attribute name to check
      * @returns true if the attribute should be excluded
      */
     private shouldExcludeAttribute;
+    /**
+     * Delete an entry of the applicative branch, tolerating its absence.
+     *
+     * A missing entry is the state we wanted, so `NoSuchObject` is not an error:
+     * it keeps the mail-change path idempotent when a hook fires twice.
+     *
+     * @param dn - DN of the applicative entry to remove
+     * @throws whatever the directory raised, except NoSuchObject
+     */
+    private deleteApplicativeEntry;
+    /**
+     * Select the attributes to copy from a user entry into an applicative entry.
+     *
+     * An allowlist (`--applicative-account-attribute`, plus `objectClass` and the
+     * mail attribute, which are forced in by the constructor):
+     * the applicative branch is only ever read to bind with `uid` and
+     * `userPassword`, so anything else the user entry happens to carry —
+     * recovery addresses, e2ee key material, whatever the schema grows next —
+     * has no reason to be duplicated there.
+     *
+     * @param entry - The source user entry
+     * @returns The subset worth copying, empty values dropped
+     */
+    private pickCopiedAttributes;
     /**
      * Whether a DN belongs to the applicative branch this plugin manages.
      *

package/docs/client-development/browser/libraries.md

@@ -23,16 +23,23 @@ This guide covers LDAP-Rest's browser libraries for building LDAP management int
   - [Installation](#ldapuniteditor-installation)
   - [Basic Usage](#ldapuniteditor-basic-usage)
   - [Features](#ldapuniteditor-features)
+- [LdapBrowser](#ldapbrowser)
+  - [Installation](#ldapbrowser-installation)
+  - [Basic Usage](#ldapbrowser-basic-usage)
+  - [Configuration Options](#ldapbrowser-configuration-options)
+  - [Public Methods](#ldapbrowser-public-methods)
+  - [RawApiClient and SchemaView](#rawapiclient-and-schemaview)
 
 ---
 
 ## Overview
 
-LDAP-Rest provides three ready-to-use browser libraries for building LDAP management interfaces:
+LDAP-Rest provides four ready-to-use browser libraries for building LDAP management interfaces:
 
 - **LdapTreeViewer** - Interactive hierarchical tree view of LDAP organizations
 - **LdapUserEditor** - Complete user management interface with organization tree, user list, and edit form
 - **LdapUnitEditor** - Organization management interface with create, move, edit, and delete operations
+- **LdapBrowser** - Low-level, read-only directory browser (tree, raw entries, schema), in the spirit of phpLDAPadmin
 
 All libraries are:
 
@@ -1174,6 +1181,140 @@ See [LDAP Organizations Plugin Documentation](../ldapOrganizations.md) for API d
 
 ---
 
+<a name="ldapbrowser"></a>
+
+## LdapBrowser
+
+A low-level, read-only browser of the directory: lazy tree on the left, raw content of the selected entry on the right, LDAP filter search on top. Attributes are annotated with the directory schema — mandatory attributes are marked, unknown ones are flagged, binary values are shown as base64 (photos as thumbnails).
+
+It consumes the [raw plugin](../../usage/plugins/ldap/raw.md), which must be loaded server-side:
+
+```bash
+ldap-rest --plugin core/ldap/raw --plugin core/static
+```
+
+<a name="ldapbrowser-installation"></a>
+
+### Installation
+
+#### Direct Browser Usage
+
+```html
+<link rel="stylesheet" href="/static/browser/ldap-browser.css" />
+<script src="/static/browser/ldap-browser.js"></script>
+```
+
+The Material Icons font is used for the tree icons:
+
+```html
+<link
+  href="https://fonts.googleapis.com/icon?family=Material+Icons"
+  rel="stylesheet"
+/>
+```
+
+#### With a Bundler
+
+```typescript
+import { LdapBrowser } from 'ldap-rest/browser-ldap-browser-index';
+```
+
+<a name="ldapbrowser-basic-usage"></a>
+
+### Basic Usage
+
+```html
+<div id="ldap-browser" style="height: 70vh"></div>
+
+<script>
+  const { LdapBrowser } = window.LdapBrowser;
+
+  const browser = new LdapBrowser({
+    containerId: 'ldap-browser',
+    apiBaseUrl: window.location.origin,
+    onEntrySelected: dn => console.log('Selected:', dn),
+    onError: error => console.error(error),
+  });
+
+  await browser.init();
+</script>
+```
+
+A ready-made demo page ([`examples/web/ldap-browser.html`](../../../examples/web/ldap-browser.html))
+is served at `/static/examples/web/ldap-browser.html`.
+
+<a name="ldapbrowser-configuration-options"></a>
+
+### Configuration Options
+
+| Option            | Type                     | Default            | Description                             |
+| ----------------- | ------------------------ | ------------------ | --------------------------------------- |
+| `containerId`     | `string`                 | _required_         | id of the element to render into        |
+| `apiBaseUrl`      | `string`                 | `''` (same origin) | Origin of the API                       |
+| `authToken`       | `string`                 | —                  | Sent as `Authorization: Bearer …`       |
+| `initialDn`       | `string`                 | first exposed base | DN selected on startup                  |
+| `onEntrySelected` | `(dn: string) => void`   | —                  | Called whenever an entry is displayed   |
+| `onError`         | `(error: Error) => void` | `console.error`    | Called on any error the browser handles |
+
+<a name="ldapbrowser-public-methods"></a>
+
+### Public Methods
+
+#### `async init(): Promise<void>`
+
+Loads the exposed bases and the schema, builds the interface and opens `initialDn`. Throws when the container does not exist or the API is unreachable. A schema that cannot be read is reported through `onError` but does not prevent browsing — the entry table is then displayed without annotations.
+
+#### `getCurrentDn(): string | null`
+
+DN currently displayed, or `null` before the first selection.
+
+#### `destroy(): void`
+
+Releases the listeners held by the tree.
+
+<a name="rawapiclient-and-schemaview"></a>
+
+### RawApiClient and SchemaView
+
+Both are exported for applications that want the data without the interface:
+
+```typescript
+import { RawApiClient, SchemaView } from 'ldap-rest/browser-ldap-browser-index';
+
+const api = new RawApiClient(window.location.origin);
+const schema = new SchemaView(await api.getSchema());
+
+const entry = await api.getEntry('uid=alice,ou=users,dc=example,dc=com');
+const { must, may } = schema.resolveAttributes(
+  entry.attributes.objectClass.values
+);
+console.log('Mandatory attributes:', must);
+console.log('Allowed attributes:', may);
+
+const { children, truncated } = await api.getChildren('dc=example,dc=com');
+const found = await api.search({
+  base: 'ou=users,dc=example,dc=com',
+  filter: '(mail=*@example.com)',
+  attributes: ['uid', 'mail'],
+});
+```
+
+`SchemaView` resolves the `SUP` chains for you: `resolveAttributes()` walks object class inheritance, `getAttributeSyntax()` walks attribute type inheritance, and `isBinaryAttribute()` / `isImageAttribute()` tell how to render a value.
+
+### API Integration
+
+The browser uses these endpoints:
+
+- `GET /api/v1/ldap/raw/bases` - Exposed subtrees, used as tree roots
+- `GET /api/v1/ldap/raw/schema` - Directory schema
+- `GET /api/v1/ldap/raw/entry/:dn` - Entry content
+- `GET /api/v1/ldap/raw/children/:dn` - Children of a node
+- `GET /api/v1/ldap/raw/search` - Filter search
+
+See [LDAP Raw Plugin Documentation](../../usage/plugins/ldap/raw.md) for API details.
+
+---
+
 ## Next Steps
 
 - **[REST API Documentation](../api/REST_API.md)** - Learn about the underlying API

package/docs/usage/configuration.md

@@ -190,8 +190,28 @@ Monitors LDAP modifications and triggers hooks for attribute changes. No configu
 
 Maintains consistency of department links when organizations are renamed/moved. No configuration options - uses [core/ldap/organizations](#coreldaporganizations) settings.
 
+#### `core/ldap/raw`
+
+Read-only low-level browsing (root DSE, schema, entries). See [raw plugin](plugins/ldap/raw.md).
+
+| CLI                           | Plural                         | Env                             | Default       | Description                     |
+| ----------------------------- | ------------------------------ | ------------------------------- | ------------- | ------------------------------- |
+| `--ldap-raw-base`             | `--ldap-raw-bases`             | `DM_LDAP_RAW_BASE`              | `--ldap-base` | Subtrees exposed by the API     |
+| `--ldap-raw-hidden-attribute` | `--ldap-raw-hidden-attributes` | `DM_LDAP_RAW_HIDDEN_ATTRIBUTES` | `[]`          | Extra attributes never returned |
+| `--ldap-raw-show-secrets`     |                                | `DM_LDAP_RAW_SHOW_SECRETS`      | `false`       | Serve credential attributes     |
+| `--ldap-raw-max-results`      |                                | `DM_LDAP_RAW_MAX_RESULTS`       | `200`         | Max entries per search/listing  |
+| `--ldap-raw-schema-cache-ttl` |                                | `DM_LDAP_RAW_SCHEMA_CACHE_TTL`  | `3600`        | Schema cache lifetime (seconds) |
+
 ### Authentication Plugins
 
+#### Common to every authentication plugin
+
+| CLI                  | Plural                 | Env                   | Default | Description                                 |
+| -------------------- | ---------------------- | --------------------- | ------- | ------------------------------------------- |
+| `--auth-path-prefix` | `--auth-path-prefixes` | `DM_AUTH_PATH_PREFIX` | `[]`    | Restrict this plugin to these path prefixes |
+
+Empty means the plugin guards every path. Scoping several instances to different prefixes lets one server serve populations that authenticate differently — see [Serving several populations from one server](plugins/auth/README.md#serving-several-populations-from-one-server), including the routes it can leave unauthenticated.
+
 #### `core/auth/token`
 
 | CLI            | Plural          | Env              | Default | Description           |
@@ -302,14 +322,29 @@ Maintains consistency of department links when organizations are renamed/moved.
 
 #### `core/twake/applicativeAccounts`
 
-| CLI                            | Plural                          | Env                              | Default       | Description                       |
-| ------------------------------ | ------------------------------- | -------------------------------- | ------------- | --------------------------------- |
-| `--applicative-account-base`   |                                 | `DM_APPLICATIVE_ACCOUNT_BASE`    |               | Applicative accounts base DN      |
-| `--max-app-accounts`           |                                 | `DM_MAX_APP_ACCOUNTS`            | `5`           | Max accounts per user             |
-| `--ldap-operational-attribute` | `--ldap-operational-attributes` | `DM_LDAP_OPERATIONAL_ATTRIBUTES` | _(see below)_ | Operational attributes to exclude |
+| CLI                               | Plural                             | Env                                 | Default       | Description                           |
+| --------------------------------- | ---------------------------------- | ----------------------------------- | ------------- | ------------------------------------- |
+| `--applicative-account-base`      |                                    | `DM_APPLICATIVE_ACCOUNT_BASE`       |               | Applicative accounts base DN          |
+| `--max-app-accounts`              |                                    | `DM_MAX_APP_ACCOUNTS`               | `5`           | Max accounts per user                 |
+| `--applicative-account-attribute` | `--applicative-account-attributes` | `DM_APPLICATIVE_ACCOUNT_ATTRIBUTES` | _(see below)_ | Attributes copied from the user entry |
+| `--ldap-operational-attribute`    | `--ldap-operational-attributes`    | `DM_LDAP_OPERATIONAL_ATTRIBUTES`    | _(see below)_ | Operational attributes to exclude     |
+
+Default copied attributes: `objectClass`, `cn`, `sn`, `givenName`, `displayName`, `description` — plus the configured mail attribute, always.
+
+This is an **allowlist**: an attribute the user entry carries but that is not
+named here is not copied into the applicative branch. That branch is only ever
+read to bind with `uid` and `userPassword`, so anything else has no reason to
+be duplicated there — and a new attribute added to the user schema later stays
+out unless someone opts in.
 
 Default operational attributes: `dn`, `controls`, `structuralObjectClass`, `entryUUID`, `entryDN`, `subschemaSubentry`, `modifyTimestamp`, `modifiersName`, `createTimestamp`, `creatorsName`, `userPassword`
 
+Operational attributes are only used when an applicative entry is **recreated
+from its own current state** (on a mail change): they are what the directory
+generates and would refuse on an `add`. `userPassword` is in that list on
+purpose — a mail change forces every client to be reconfigured anyway, so app
+accounts are deliberately reissued without a password.
+
 #### `core/twake/appAccountsConsistency`
 
 Automatically creates/updates/deletes applicative account entries when users are created/modified/deleted. No configuration options - uses [core/twake/applicativeAccounts](#coretwakeapplicativeaccounts) settings.

package/docs/usage/plugins/README.md

@@ -6,15 +6,16 @@ LDAP-Rest is extensible through a plugin system. This section documents all avai
 
 LDAP entity management:
 
-| Plugin                                   | Description                                             |
-| ---------------------------------------- | ------------------------------------------------------- |
-| [flat-generic](ldap/flat-generic.md)     | Generic LDAP entity management (users, positions, etc.) |
-| [groups](ldap/groups.md)                 | LDAP group management with member validation            |
-| [organizations](ldap/organizations.md)   | Hierarchical organization management                    |
-| [bulk-import](ldap/bulk-import.md)       | Bulk import from CSV                                    |
-| [trash](ldap/trash.md)                   | Trash system (soft delete)                              |
-| [external-users](ldap/external-users.md) | Automatic external contact creation                     |
-| [on-change](ldap/on-change.md)           | LDAP change detection                                   |
+| Plugin                                   | Description                                               |
+| ---------------------------------------- | --------------------------------------------------------- |
+| [flat-generic](ldap/flat-generic.md)     | Generic LDAP entity management (users, positions, etc.)   |
+| [groups](ldap/groups.md)                 | LDAP group management with member validation              |
+| [organizations](ldap/organizations.md)   | Hierarchical organization management                      |
+| [bulk-import](ldap/bulk-import.md)       | Bulk import from CSV                                      |
+| [trash](ldap/trash.md)                   | Trash system (soft delete)                                |
+| [external-users](ldap/external-users.md) | Automatic external contact creation                       |
+| [on-change](ldap/on-change.md)           | LDAP change detection                                     |
+| [raw](ldap/raw.md)                       | Low-level browsing: root DSE, schema, entries (read-only) |
 
 ## Authentication Plugins
 

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

@@ -43,6 +43,63 @@ LDAP-Rest provides multiple authentication plugins to secure API access. These p
 | **Best For**           | APIs, Scripts | APIs, Enhanced    | Backend Services       | Enterprises with LLNG | Cloud/SaaS, Enterprises with SSO |
 | **Dependencies**       | None          | None              | None                   | lemonldap-ng-handler  | express-openid-connect           |
 
+## Serving several populations from one server
+
+Populations rarely authenticate the same way: machines carry a token, administrators arrive with an SSO session. `--auth-path-prefix` restricts an authentication plugin to one or more path prefixes, so a single server can host both without either credential being valid on the other's branch of the API.
+
+Any plugin can be loaded more than once under a distinct name with its own configuration (`module:name:{json}`), which is what makes this work:
+
+```bash
+ldap-rest \
+  --plugin 'core/auth/token:auth-machines:{"auth_path_prefix":"/api/m","auth_token":"…:robot"}' \
+  --plugin 'core/ldap/raw:raw-machines:{"api_prefix":"/api/m"}' \
+  --plugin 'core/auth/openidconnect:auth-admins:{"auth_path_prefix":"/api/admin"}' \
+  --plugin 'core/ldap/raw:raw-admins:{"api_prefix":"/api/admin"}'
+```
+
+A token presented on `/api/admin` is refused, and a session presented on `/api/m` is refused too: each authentication plugin only sees the branch it was mounted on. Prefixes match on segment boundaries, so `/api/m` guards `/api/m` and `/api/m/entry` but never `/api/machines`.
+
+A prefix must be a string starting with `/`. Anything else — a number left in the JSON, an empty entry, a prefix without its leading slash — refuses to start rather than being skipped: a dropped entry shrinks what the plugin guards, which is the failure that leaves a branch open while the configuration still reads as if it were covered. `/` is not a prefix but the whole server, so a list containing it makes the plugin a catch-all: `["/", "/api/admin"]` guards everything, not only `/api/admin`.
+
+### One branch apart, a token on everything else
+
+Leaving a plugin unscoped makes it the **catch-all**: it guards everything no scoped plugin claims. There is no list of "everything else" to write, and none to keep up to date when a route is added:
+
+```bash
+ldap-rest \
+  --plugin 'core/auth/openidconnect:auth-admins:{"auth_path_prefix":"/api/admin"}' \
+  --plugin core/auth/token \
+  --auth-token "…:robot"
+```
+
+`/api/admin` requires the SSO session, everything else requires the token.
+
+### How the choice is made
+
+Authentication is not a middleware each plugin mounts for itself. The server mounts **one dispatcher**, positioned after the guards (`protect`: rate limiting, proxy trust, CrowdSec) and access logging, and before the first plugin able to register a route. Authentication plugins register with it instead of adding a layer.
+
+Two properties follow, and both are load-bearing:
+
+- **Order of declaration does not matter.** A plugin that registers after the API it guards still guards it, because the dispatcher — not the plugin — owns the layer. With per-plugin middlewares that was untrue and silent: a guard mounted after its routes never ran for them.
+- **The most specific claim wins.** `/api/admin` is handled by the plugin scoped to it, `/api` by the plugin scoped to `/api`, and anything unclaimed by an unscoped plugin. Only the winner runs, so two plugins covering the same request never compose as an AND that no credential can satisfy.
+
+Several plugins sharing the same winning prefix all run, in registration order: requiring two credentials on one branch is a legitimate ask, and an accident there fails closed rather than open.
+
+### The gap to watch
+
+A route registered **outside every prefix is served without authentication**. That is the price of scoping, and it is silent — the server starts, the API answers. To make it visible, the routes no plugin guards are listed at startup:
+
+```
+Authentication is restricted to /api/m, /api/admin, so these routes are
+served without authentication: /api/v1/config, /api/v1/ldap/users
+```
+
+Read that line on every configuration change. Either scope the missing routes to a prefix as well, add an unscoped plugin as the catch-all, or keep them public deliberately. Nothing is reported when no authentication is configured (the server is open on purpose) or when a catch-all covers what the scoped plugins do not.
+
+Note the converse: with a catch-all there is no public branch at all. Making one API reachable without credentials means scoping every authentication plugin and leaving that branch out — the warning will then name it, which is correct but reads as an oversight rather than a decision.
+
+Note that a prefix scopes **authentication**, not authorization: once past it, a caller reaches everything the branch exposes. Restrict what each population may do with [authz-per-route](authz-per-route.md) or [authz-per-branch](authz-per-branch.md).
+
 ## Combining with Authorization
 
 All authentication plugins set `req.user` to the authenticated identity. You can use hooks to implement custom authorization:

package/docs/usage/plugins/auth/rate-limit.md

@@ -54,6 +54,15 @@ For correct IP detection behind reverse proxies:
 
 The rate limiter will use the real client IP from `X-Forwarded-For` when the request comes from a trusted proxy.
 
+This pairing is not a refinement, it is what makes the limit hold. The limiter keys on `X-Forwarded-For`, a header any client can set to anything; `trustedProxy` is what strips it on requests that do not come from a declared proxy. Loaded alone, the limiter counts forged keys: rotating the header on every attempt gives an attacker a fresh counter each time, and the brute-force protection becomes decorative while still looking configured. The plugin therefore warns at startup when `trustedProxy` is absent:
+
+```
+Auth rate limiting keys on X-Forwarded-For but core/auth/trustedProxy is not
+loaded: a client can forge that header and evade the limit.
+```
+
+Either load `trustedProxy`, or make sure the reverse proxy in front **overwrites** `X-Forwarded-For` rather than appending to it.
+
 ## Security Considerations
 
 - Always use with `trustedProxy` plugin behind reverse proxies