ldap-rest 2.1.0 → 2.2.0

package/dist/src/plugins/auth/authzLinid1.d.ts

@@ -1,11 +1,3 @@
-/**
- * @module plugins/auth/authzLinid1
- * @author Xavier Guimard <xguimard@linagora.com>
- *
- * Authorization plugin based on twakeLocalAdminLink LDAP attribute
- * Grants permissions to users referenced in organization's twakeLocalAdminLink
- * @group Plugins
- */
 import type { DM } from '../../bin/index.js';
 import type { Hooks } from '../../hooks.js';
 import type { BranchPermissions } from '../../config/args.js';
@@ -21,6 +13,7 @@ export default class AuthzLinid1 extends AuthzBase {
         authz_global_branch: import("../../config/options.js").ArrayOption;
         authz_global_write_branch: import("../../config/options.js").ArrayOption;
         authz_global_organization: import("../../config/options.js").StringOption;
+        authz_group_admin_attribute: import("../../config/options.js").StringOption;
     };
     name: string;
     permissionsCache: Map<string, CachedPermissions>;
@@ -30,12 +23,97 @@ export default class AuthzLinid1 extends AuthzBase {
      * into the cache afterwards.
      */
     private permissionsGeneration;
-    hooks: AuthzBase['hooks'] & Pick<Hooks, 'ldapmodifydone' | 'ldapdeletedone' | 'ldaprenamedone'>;
+    /** The delegation attribute, when the feature is on. */
+    private readonly groupAdminAttr;
+    private readonly adminAttr;
+    private reducedFilterNames?;
+    /**
+     * Marks a search whose projection we widened for the delegation attribute.
+     * As in the base class, a symbol survives the copies another plugin makes.
+     */
+    private static readonly widenedForDelegation;
+    hooks: AuthzBase['hooks'] & Pick<Hooks, 'ldapmodifydone' | 'ldapdeletedone' | 'ldaprenamedone' | 'ldapsearchrequest' | 'ldapsearchfilter' | 'ldapmodifyrequest'>;
     /** What the classes above declared, read once this one is constructed */
     private readonly declaredByBase;
     constructor(server: DM);
     /** Drop every cached permission lookup. */
     forgetPermissions(): void;
+    /**
+     * Add the delegation attribute to a search projection the caller did not
+     * ask it in: the filter below cannot tell a delegated group from any other
+     * entry without it. It is removed again once the result is judged.
+     */
+    private widenForDelegation;
+    /**
+     * Keep a delegated group the attachment filter would hide, and show only
+     * the members of it this caller manages. A group the caller administers
+     * through its organization keeps the ordinary answer, members included:
+     * the delegation is an addition to that path, not a restriction on it.
+     */
+    private filterDelegatedGroups;
+    /** Remove the delegation attribute a search only carried for this judgement. */
+    private stripWidened;
+    /**
+     * Judge a change to a group whose membership is delegated: a delegated
+     * administrator may add or remove members they manage, and change nothing
+     * else on the group.
+     *
+     * An ordinary administrator of the group goes through the base checks
+     * untouched, as does a caller the delegation does not reach.
+     */
+    private judgeDelegatedGroup;
+    /** The fields a group schema gives its members and owners. */
+    private groupAttributes;
+    /**
+     * The filter names that test the member and owner values we reduce: their
+     * own names and OIDs, and every supertype they answer under. A filter on
+     * `distinguishedName`, which both inherit, tests both.
+     */
+    private memberFilterNames;
+    private resolveMemberFilterNames;
+    /** Whether `dn` is in a branch only its organization's administrators read. */
+    private isGlobalBranch;
+    /**
+     * Keep only the members and owners this caller manages, in place.
+     *
+     * @param entry group entry about to be answered
+     * @param delegations the organizations the group delegates to
+     * @param manages tells whether a member's organization is one of them
+     */
+    private keepManagedMembers;
+    /** The organizations a group delegates membership management to. */
+    private delegationsOf;
+    /** Whether a member's organization lies in one of the delegated branches. */
+    private withinDelegation;
+    /** The organization a member is attached to, and nothing else. */
+    private storedOrganization;
+    /** The delegation of a group, and its stored entry. */
+    private storedGroup;
+    /** A DN as a key two spellings of it share. */
+    private dnKey;
+    /** `isDnInBranch`, with a malformed DN judged as outside. */
+    private within;
+    /**
+     * Refuse a delegated change that is not an add or delete of a member the
+     * caller manages.
+     */
+    private assertDelegatedChanges;
+    /** Whether the caller manages a member: it is attached to one of theirs. */
+    private managesMember;
+    /** The group plugin's placeholder, which takes the last member's place. */
+    private isDummyMember;
+    /**
+     * The groups a caller manages the members of through a delegation, for
+     * `GET /authz/scope`. Read on each call: a group's delegation is a handful
+     * of entries, and the scope is not on a request's hot path.
+     *
+     * @param user the caller's DN
+     * @returns the delegated groups, empty when the option is off
+     */
+    delegatedGroups(user: string): Promise<{
+        dn: string;
+        manageMembers: boolean;
+    }[]>;
     /**
      * The organizations naming `dn` an administrator. Taking one of those
      * accounts over grants its branches, so the base refuses a caller who
@@ -77,8 +155,24 @@ export default class AuthzLinid1 extends AuthzBase {
     protected sourcePermission(branch: string): keyof BranchPermissions;
     /**
      * Resolve user - for authzLinid1, convert uid to userDn via LDAP
+     *
+     * An account the schema marks with a state other than `enabled` is
+     * refused: the identity provider may still let it sign in, and the
+     * lifecycle state is the directory's way to stop it.
      */
     resolveUser(uid: string): Promise<string | null>;
+    /**
+     * The attribute carrying an account's lifecycle state, and the value that
+     * means enabled, from the flat entity schema holding `dn`.
+     */
+    private accountStatus;
+    /**
+     * Whether the account carries the enabled state, or carries no status at
+     * all: an entry the schema does not manage keeps the access it had.
+     */
+    private enabled;
+    /** The account status attributes the loaded user schemas declare. */
+    private statusAttributes;
     /**
      * Get user DN from uid
      *

package/dist/src/plugins/auth/authzScope.d.ts

@@ -15,6 +15,10 @@ export declare const ScopeResponse: import("@sinclair/typebox").TObject<{
         path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     transit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNull]>>;
+    delegatedGroups: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        dn: import("@sinclair/typebox").TString;
+        manageMembers: import("@sinclair/typebox").TBoolean;
+    }>>>;
     linksAnyDomain: import("@sinclair/typebox").TBoolean;
     passwordPolicies: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     entities: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{

package/dist/src/plugins/auth/crowdsec.d.ts

@@ -27,8 +27,15 @@ export default class CrowdSec extends DmPlugin {
     private apiKey;
     private cacheTtl;
     private cache;
+    private lastSweep;
+    /** Distinct addresses remembered at once, so a rotating header cannot grow the map. */
+    private static readonly MAX_CLIENTS;
     constructor(...args: ConstructorParameters<typeof DmPlugin>);
     api(app: Express): void;
     private checkIpBanned;
+    /** Drop expired decisions, at most once a TTL, and keep the map bounded. */
+    private prune;
+    /** Drop the oldest decision: `Map` keeps insertion order. */
+    private evictOldest;
     private getClientIp;
 }

package/dist/src/plugins/auth/rateLimit.d.ts

@@ -24,7 +24,14 @@ export default class RateLimit extends DmPlugin {
     private store;
     private windowMs;
     private maxRequests;
+    private lastSweep;
+    /** Distinct addresses remembered at once, so a rotating header cannot grow the map. */
+    private static readonly MAX_CLIENTS;
     constructor(...args: ConstructorParameters<typeof DmPlugin>);
     api(app: Express): void;
+    /** Drop expired counters, at most once a window, and keep the map bounded. */
+    private prune;
+    /** Drop the oldest counter: `Map` keeps insertion order. */
+    private evictOldest;
     private getClientIp;
 }

package/dist/src/plugins/auth/totp.d.ts

@@ -14,12 +14,23 @@ export default class AuthTotp extends AuthBase {
     private totpUsers;
     private window;
     private step;
+    /** Last counter accepted per user, so an observed code is not reusable. */
+    private lastCounters;
     constructor(...args: ConstructorParameters<typeof AuthBase>);
     authMethod(req: DmRequest, res: Response, next: () => void): void;
+    /**
+     * Whether a counter is new for this user: a code is accepted once, so an
+     * observed one is not a bearer credential for the rest of its window.
+     */
+    private acceptCounter;
     /**
      * Verify a TOTP token against a secret
+     *
+     * @returns the counter it matched, or null
      */
     private verifyTotp;
+    /** Compare two codes without letting a difference shorten the comparison. */
+    private sameCode;
     /**
      * Generate a TOTP token using HMAC-SHA1
      */

package/dist/src/plugins/auth/trustedProxy.d.ts

@@ -5,6 +5,8 @@ declare global {
         interface Request {
             trustedProxy?: boolean;
             proxyAuthUser?: string;
+            /** The client address, read through the trusted proxy chain. */
+            clientIp?: string;
         }
     }
 }
@@ -19,6 +21,27 @@ export default class TrustedProxy extends DmPlugin {
     private authHeader;
     constructor(...args: ConstructorParameters<typeof DmPlugin>);
     api(app: Express): void;
+    /**
+     * The client address in a proxy chain: walk `X-Forwarded-For` from the
+     * right, skip the addresses this server trusts as proxies, and take the
+     * first one it does not. A port is stripped from the entry (`ip:port`,
+     * `[v6]:port`) since some proxies write one.
+     *
+     * An entry that is not an address stops the walk and the peer is used: the
+     * entries to its left are the ones a client wrote, so continuing would let
+     * it choose the address. A chain made only of trusted addresses falls back
+     * to the peer too.
+     *
+     * @param xff the header as received from a trusted peer
+     * @param remoteAddr the TCP peer
+     * @returns the address to key rate limits and logs on
+     */
+    private clientIpFromXff;
+    /**
+     * An `X-Forwarded-For` entry as an address: a plain one, a bracketed IPv6
+     * address, or either carrying a port. Anything else is undefined.
+     */
+    private forwardedAddress;
     /**
      * Check if an IP address belongs to a trusted proxy network
      */

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

@@ -17,6 +17,13 @@ export default class LdapBulkImport extends DmPlugin {
     private readonly settings;
     private resources;
     private upload;
+    /**
+     * The branches the import writes into. An authorization plugin judges an
+     * added entry on its link rather than on a flat store it lands in.
+     *
+     * @returns the distinct resource bases
+     */
+    bases(): string[];
     constructor(parent: DM);
     api(app: Express): void;
     /**

package/docs/client-development/schemas/README.md

@@ -602,13 +602,14 @@ Semantic roles assign special meaning to attributes for UI and business logic ha
 
 ### Available Roles
 
-| Role           | Description                        | Example Attribute                        | Usage                                 |
-| -------------- | ---------------------------------- | ---------------------------------------- | ------------------------------------- |
-| `identifier`   | Primary identifier (RDN attribute) | `uid`, `cn`, `sAMAccountName`            | Used as the entry's unique identifier |
-| `displayName`  | Human-readable display name        | `cn`, `displayName`                      | Shown in lists and UI elements        |
-| `primaryEmail` | Main email address                 | `mail`, `userPrincipalName`              | Primary contact email                 |
-| `emailAliases` | Additional email addresses         | `mailAlternateAddress`, `proxyAddresses` | Alternative email addresses           |
-| `emailQuota`   | Email storage quota                | `mailQuota`, `mailQuotaSize`             | Storage limit for mailbox             |
+| Role                      | Description                                                       | Example Attribute                        | Usage                                 |
+| ------------------------- | ----------------------------------------------------------------- | ---------------------------------------- | ------------------------------------- |
+| `identifier`              | Primary identifier (RDN attribute)                                | `uid`, `cn`, `sAMAccountName`            | Used as the entry's unique identifier |
+| `displayName`             | Human-readable display name                                       | `cn`, `displayName`                      | Shown in lists and UI elements        |
+| `primaryEmail`            | Main email address                                                | `mail`, `userPrincipalName`              | Primary contact email                 |
+| `emailAliases`            | Additional email addresses                                        | `mailAlternateAddress`, `proxyAddresses` | Alternative email addresses           |
+| `emailQuota`              | Email storage quota                                               | `mailQuota`, `mailQuotaSize`             | Storage limit for mailbox             |
+| `groupAdminOrganizations` | Organizations whose administrators manage the group's own members | `twakeGroupAdminOrgLink`                 | Delegated group membership            |
 
 ### Role Usage Examples
 

package/docs/usage/configuration.md

@@ -456,13 +456,14 @@ whichever of the two names it selects. A value other than `req.user` or
 
 #### `core/auth/authzLinid1`
 
-| CLI                                                             | Env                              | Default                   | Description                                                                                                                                                                                   |
-| --------------------------------------------------------------- | -------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--authz-local-admin-attribute`                                 | `DM_AUTHZ_LOCAL_ADMIN_ATTRIBUTE` | `twakeLocalAdminLink`     | Local admin attribute                                                                                                                                                                         |
-| `--authz-linid1-cache-ttl`                                      | `DM_AUTHZ_LINID1_CACHE_TTL`      | `300`                     | Seconds a user's resolved permissions are cached; a write touching the admin attribute clears the cache at once                                                                               |
-| `--authz-global-branch` / `--authz-global-branches`             | `DM_AUTHZ_GLOBAL_BRANCHES`       |                           | Branches outside the tree only the administrators of `--authz-global-organization` read and write, [details](plugins/auth/authz-linid1.md#global-branches)                                    |
-| `--authz-global-write-branch` / `--authz-global-write-branches` | `DM_AUTHZ_GLOBAL_WRITE_BRANCHES` |                           | Branches outside the tree every administrator reads and only the administrators of `--authz-global-organization` write and delete in, [details](plugins/auth/authz-linid1.md#global-branches) |
-| `--authz-global-organization`                                   | `DM_AUTHZ_GLOBAL_ORGANIZATION`   | `--ldap-top-organization` | The organization holding the global branches and global write branches                                                                                                                        |
+| CLI                                                             | Env                              | Default                   | Description                                                                                                                                                                                        |
+| --------------------------------------------------------------- | -------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-local-admin-attribute`                                 | `DM_AUTHZ_LOCAL_ADMIN_ATTRIBUTE` | `twakeLocalAdminLink`     | Local admin attribute                                                                                                                                                                              |
+| `--authz-linid1-cache-ttl`                                      | `DM_AUTHZ_LINID1_CACHE_TTL`      | `300`                     | Seconds a user's resolved permissions are cached; a write touching the admin attribute clears the cache at once                                                                                    |
+| `--authz-global-branch` / `--authz-global-branches`             | `DM_AUTHZ_GLOBAL_BRANCHES`       |                           | Branches outside the tree only the administrators of `--authz-global-organization` read and write, [details](plugins/auth/authz-linid1.md#global-branches)                                         |
+| `--authz-global-write-branch` / `--authz-global-write-branches` | `DM_AUTHZ_GLOBAL_WRITE_BRANCHES` |                           | Branches outside the tree every administrator reads and only the administrators of `--authz-global-organization` write and delete in, [details](plugins/auth/authz-linid1.md#global-branches)      |
+| `--authz-global-organization`                                   | `DM_AUTHZ_GLOBAL_ORGANIZATION`   | `--ldap-top-organization` | The organization holding the global branches and global write branches                                                                                                                             |
+| `--authz-group-admin-attribute`                                 | `DM_AUTHZ_GROUP_ADMIN_ATTRIBUTE` |                           | Attribute on a group naming the organizations whose administrators manage their own members; empty means the delegation is off, [details](plugins/auth/authz-linid1.md#delegated-group-membership) |
 
 ### Security Plugins
 

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

@@ -181,18 +181,18 @@ base class, but nothing obliges a third implementation to.
 
 ## Choosing an Authentication Method
 
-| Feature                | Token         | TOTP              | HMAC                   | LemonLDAP::NG         | OpenID Connect                   |
-| ---------------------- | ------------- | ----------------- | ---------------------- | --------------------- | -------------------------------- |
-| **Setup Complexity**   | Simple        | Simple            | Medium                 | Medium                | Medium                           |
-| **User Management**    | None          | Manual            | Manual (service-based) | External (LLNG)       | External (Provider)              |
-| **SSO Support**        | No            | No                | No                     | Yes                   | Yes                              |
-| **MFA Support**        | No            | Yes (TOTP itself) | N/A                    | Yes (via LLNG)        | Yes (via Provider)               |
-| **Session Management** | Stateless     | Stateless         | Stateless              | LLNG Sessions         | OIDC Sessions                    |
-| **Code Expiration**    | Never         | 30-60 seconds     | Per-request            | Session-based         | Session-based                    |
-| **Request Integrity**  | No            | No                | Yes (body + path hash) | No                    | No                               |
-| **Replay Protection**  | No            | Yes (time-based)  | Yes (timestamp)        | Session-based         | Session-based                    |
-| **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           |
+| Feature                | Token         | TOTP                      | HMAC                   | LemonLDAP::NG         | OpenID Connect                   |
+| ---------------------- | ------------- | ------------------------- | ---------------------- | --------------------- | -------------------------------- |
+| **Setup Complexity**   | Simple        | Simple                    | Medium                 | Medium                | Medium                           |
+| **User Management**    | None          | Manual                    | Manual (service-based) | External (LLNG)       | External (Provider)              |
+| **SSO Support**        | No            | No                        | No                     | Yes                   | Yes                              |
+| **MFA Support**        | No            | Yes (TOTP itself)         | N/A                    | Yes (via LLNG)        | Yes (via Provider)               |
+| **Session Management** | Stateless     | Stateless                 | Stateless              | LLNG Sessions         | OIDC Sessions                    |
+| **Code Expiration**    | Never         | 30-60 seconds             | Per-request            | Session-based         | Session-based                    |
+| **Request Integrity**  | No            | No                        | Yes (body + path hash) | No                    | No                               |
+| **Replay Protection**  | No            | Yes (single-use code)     | Yes (timestamp)        | Session-based         | Session-based                    |
+| **Best For**           | APIs, Scripts | MFA, one request per step | 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
 

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

@@ -11,6 +11,7 @@ The `authzLinid1` plugin provides dynamic, LDAP-driven access control by reading
 - **Full CRUD rights** - Local admins get read, write, and delete permissions
 - **Sub-branch inheritance** - Permissions apply recursively to sub-branches
 - **Cross-branch access** - Users/groups can be managed if their `twakeDepartmentLink` points to an authorized organization
+- **Delegated group membership** - A group can let other organizations' administrators manage their own members ([details](#delegated-group-membership))
 - **Permission caching** - Configurable TTL reduces LDAP queries (default: 5 minutes)
 
 ## How It Works
@@ -238,6 +239,56 @@ other: the global branch would hide the write branch it holds from the
 administrators meant to read it. In either case the server refuses to
 start.
 
+### Delegated group membership
+
+A group may delegate membership management to the administrators of other
+organizations, so that a group spanning several organizations can be
+maintained by each of them without opening the others' members. Off by
+default: name the attribute to turn it on.
+
+```bash
+--authz-group-admin-attribute twakeGroupAdminOrgLink
+```
+
+The attribute is multi-valued and holds organization DNs. The Twake group
+schema declares it as `twakeGroupAdminOrgLink` (`groupAdminOrganizations`
+role, `referentialIntegrity: remove`), and `twakeGroup` and
+`twakeStaticGroup` must allow it (`MAY`).
+
+Let `D` be the organizations a group delegates to, `L` the organization a
+member is attached to (its link attribute), and `C` the caller's written
+branches. Then:
+
+- `C` reads the group when a branch of `C` lies in one of the `D`.
+- `C` reads a member or owner of the group only when it is attached to an
+  `L` inside some `D` and `C` writes `L`. A member attached to no
+  organization (in transit) is neither read nor managed through the
+  delegation.
+- `C` adds or removes a `member` under the same rule. Nothing else on the
+  group changes: not its description, delegation, name, position or
+  existence. The delegation grants no creation, rename, move or delete of a
+  group.
+- The group's own administrators keep the whole group and every right they
+  had. A group attached to no organization is already readable by every
+  administrator; the delegation only adds the member write there. A member
+  that is a group follows the same link rule.
+
+Removing the last real member keeps the group plugin's rule: the placeholder
+takes its place, or the request is refused with `409`.
+
+A search whose filter tests `member`, `owner`, or a supertype they inherit
+(`distinguishedName`) does not return a delegated group: the directory judged
+the full group, and answering from the filtered membership would tell the
+caller whether a user of another organization belongs to it. The group stays
+in the ordinary listing and can be read directly.
+
+`GET /api/v1/authz/scope` lists the delegated groups under
+`delegatedGroups`, so a client does not duplicate the rule
+([scope](authz-scope.md#delegated-groups)).
+
+The delegation is read from the group entry, so a change takes effect at
+once; the plugin does not keep a second copy of it.
+
 ## Configuration
 
 No configuration file needed - permissions are read from LDAP. Simply load the plugin:
@@ -293,6 +344,17 @@ 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.
 
+### Account status
+
+When the user schema declares an `accountStatus` attribute, the resolved
+caller must carry its `states.enabled` value; any other value is refused with
+`403`, like an identity that does not resolve. A disabled, no-access or
+to-delete administrator therefore loses the API even when the identity
+provider still lets them sign in, and cannot re-enable themselves through the
+console. A write through this server that changes the status drops the
+resolved identity at once; a change made directly in the directory waits for
+`--authz-linid1-cache-ttl`.
+
 ## Permission Resolution
 
 For each LDAP operation, the plugin:
@@ -520,6 +582,13 @@ User makes request → Check cache → (if expired) Search LDAP once → Cache f
 
 - `twakeDepartmentLink` (single-valued) - DN of parent organization
 
+**Groups, when `--authz-group-admin-attribute` is set:**
+
+- `twakeGroupAdminOrgLink` (multi-valued) - DNs of the organizations whose
+  administrators manage their own members
+  ([delegated group membership](#delegated-group-membership)). The directory's
+  `twakeGroup` and `twakeStaticGroup` object classes must allow it.
+
 ### Example Schema
 
 ```ldif

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

@@ -93,6 +93,12 @@ GET /api/v1/authz/scope
       "delete": true
     }
   ],
+  "delegatedGroups": [
+    {
+      "dn": "cn=all-staff,ou=groups,dc=example,dc=com",
+      "manageMembers": true
+    }
+  ],
   "entities": [
     { "name": "users", "base": "ou=users,dc=example,dc=com", "create": true },
     { "name": "groups", "base": "ou=groups,dc=example,dc=com", "create": true },
@@ -105,6 +111,14 @@ GET /api/v1/authz/scope
 }
 ```
 
+### Delegated groups
+
+`delegatedGroups` lists the groups the caller reads, and whose members of
+their own organizations they may add or remove, through
+[`--authz-group-admin-attribute`](authz-linid1.md#delegated-group-membership).
+It is absent when that option is off or the caller has none. A client that
+does not know the field keeps working.
+
 `name` and `path` come from the branch entry itself, so an interface can show
 the scope in the directory's own words rather than as a raw DN.
 

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

@@ -52,16 +52,21 @@ For correct IP detection behind reverse proxies:
 --rate-limit-max 100
 ```
 
-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:
+The limiter reads the client address `trustedProxy` publishes on the request
+(`req.clientIp`). That plugin walks `X-Forwarded-For` from the right, skips
+the addresses it trusts as proxies, and takes the first one it does not, so a
+value a client writes at the left of the chain never becomes its key. Without
+`trustedProxy`, the limiter uses the TCP peer and a reverse proxy makes every
+client share one counter; the plugin says so at startup:
 
 ```
-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.
+Auth rate limiting ignores X-Forwarded-For because core/auth/trustedProxy is
+not loaded and uses the TCP peer: requests through a proxy share one counter.
 ```
 
-Either load `trustedProxy`, or make sure the reverse proxy in front **overwrites** `X-Forwarded-For` rather than appending to it.
+Load `trustedProxy` when a reverse proxy sits in front. It is no longer
+necessary for the proxy to overwrite the header: appending
+(`$proxy_add_x_forwarded_for`) is read correctly.
 
 ## Security Considerations
 

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

@@ -58,7 +58,7 @@ Include the current TOTP code in the `Authorization` header:
 
 ```bash
 # Get current TOTP code from your authenticator app
-curl -H "Authorization: Bearer 123456" \
+curl -H "Authorization: Bearer admin:123456" \
   http://localhost:8081/api/v1/ldap/users
 ```
 
@@ -80,6 +80,7 @@ import {
 
 const client = new TotpAuthClient({
   secret: 'JBSWY3DPEHPK3PXP',
+  user: 'admin',
   digits: 6,
   step: 30,
 });
@@ -97,12 +98,18 @@ console.log(`Current TOTP code: ${code}`);
 
 ## How It Works
 
-1. Extracts TOTP code from `Authorization: Bearer <code>` header
-2. Generates expected TOTP codes for current time window
-3. Validates code against all configured users' secrets
-4. Supports multiple time windows (±window × step seconds) for clock drift tolerance
-5. Sets `req.user` to the user's name on successful validation
-6. Returns 401 Unauthorized if code is missing, invalid, or expired
+1. Extracts the user name and TOTP code from
+   `Authorization: Bearer <name>:<code>`
+2. Looks up that user and generates the expected codes for the current time
+   window
+3. Validates the code against that user's secret, in constant time
+4. Accepts a counter once per user: a replay, or the same code twice inside
+   one time step, is refused
+5. Supports multiple time windows (±window × step seconds) for clock drift
+   tolerance
+6. Sets `req.user` to the user's name on successful validation
+7. Returns 401 Unauthorized if the name is missing or unknown, or the code is
+   missing, invalid, replayed or expired
 
 ## Multi-User Example
 
@@ -126,7 +133,7 @@ INFO: TOTP authentication successful for user: api-service
 - **Enhanced Security**: Dynamic codes that expire every 30 seconds
 - **No Shared Secrets**: Each user/service has unique TOTP secret
 - **Compatible**: Works with Google Authenticator, Authy, 1Password, etc.
-- **API Access**: Suitable for automated scripts with TOTP generation
+- **API Access**: One code per request; a client making several calls must wait for the next step or use a session token
 - **Multi-Factor**: Can be combined with other authentication methods
 
 ## Security Considerations
@@ -136,7 +143,11 @@ INFO: TOTP authentication successful for user: api-service
 - **Clock Synchronization**: Ensure server and client clocks are synchronized (NTP recommended)
 - **Window Size**: Larger windows are more tolerant but slightly less secure
 - **Secret Rotation**: Rotate TOTP secrets periodically for better security
-- **Rate Limiting**: Consider adding rate limiting to prevent brute force attacks
+- **Rate Limiting**: Load `core/auth/rateLimit`; a six-digit code is still guessable without it
+- **Single use**: A code is accepted once per user, so a second request with
+  the same code in the same step is refused. The record is per process: with
+  several replicas, a code can be used once against each until they share
+  state
 
 ## Browser Client Features
 
@@ -147,14 +158,14 @@ import {
   generateTotp,
   getRemainingSeconds,
   isValidBase32,
-  TotpAuthClient
+  TotpAuthClient,
 } from 'ldap-rest/browser-shared-utils-totp';
 
 // Generate TOTP code
 const code = await generateTotp({
   secret: 'JBSWY3DPEHPK3PXP',
   digits: 6,
-  step: 30
+  step: 30,
 });
 
 // Check validity time
@@ -169,16 +180,25 @@ if (isValidBase32('JBSWY3DPEHPK3PXP')) {
 // HTTP client with automatic TOTP authentication
 const client = new TotpAuthClient({
   secret: 'JBSWY3DPEHPK3PXP',
+  user: 'admin',
   digits: 6,
-  step: 30
+  step: 30,
 });
 
-// All HTTP methods automatically include TOTP in Authorization header
-await client.post('/api/v1/ldap/users', { uid: 'user1', ... });
-await client.put('/api/v1/ldap/users/user1', { mail: 'new@example.com' });
-await client.delete('/api/v1/ldap/users/user1');
+// Every request carries the current code; a code is accepted once, so this
+// works for one call per time step. Wait for the next code before the next.
+const created = await client.post('/api/v1/ldap/users', {
+  uid: 'user1',
+  mail: 'user1@example.com',
+});
 ```
 
+**One request per code step.** TOTP has no session: each request is
+authenticated on its own. A code is accepted once per user, so a second
+request in the same 30-second step is refused. A client making several calls
+must wait for the next code, or use another authentication plugin for the
+session after the first TOTP call.
+
 **Module Export:** `ldap-rest/browser-shared-utils-totp`
 
 **Live Demo:** Run the server and open [http://localhost:8081/static/examples/web/totp-client.html](http://localhost:8081/static/examples/web/totp-client.html)
@@ -193,7 +213,7 @@ await client.delete('/api/v1/ldap/users/user1');
 2. Check system clock synchronization (use NTP)
 3. Increase `--auth-totp-window` if experiencing timing issues
 4. Ensure code is used immediately (codes expire every 30s)
-5. Verify `Authorization: Bearer {code}` format
+5. Verify the `Authorization: Bearer <name>:<code>` format and that the name is one configured in `--auth-totp`
 
 **Problem:** Codes don't match authenticator app