ldap-rest 0.8.2 → 0.9.0

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
 

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/usage/configuration.md

@@ -25,8 +25,11 @@ All LDAP-Rest configuration options.
     - [core/auth/hmac](#coreauthhmac)
     - [core/auth/llng](#coreauthllng)
     - [core/auth/openidconnect](#coreauthopenidconnect)
+    - [core/bcl](#corebcl)
   - [Authorization Plugins](#authorization-plugins)
+    - [Common to every authorization plugin](#common-to-every-authorization-plugin)
     - [core/auth/authzPerBranch](#coreauthauthzperbranch)
+    - [core/auth/authzScope](#coreauthauthzscope)
     - [core/auth/authzPerRoute](#coreauthauthzperroute)
     - [core/auth/authzLinid1](#coreauthauthzlinid1)
   - [Security Plugins](#security-plugins)
@@ -41,6 +44,7 @@ All LDAP-Rest configuration options.
   - [Utility Plugins](#utility-plugins)
     - [core/static](#corestatic)
     - [core/weblogs](#coreweblogs)
+    - [core/storage](#corestorage)
     - [core/configApi](#coreconfigapi)
 - [Configuration File](#configuration-file)
 - [LDAP Failover](#ldap-failover)
@@ -251,27 +255,86 @@ Empty means the plugin guards every path. Scoping several instances to different
 
 #### `core/auth/llng`
 
-| CLI          | Env           | Default                              | Description               |
-| ------------ | ------------- | ------------------------------------ | ------------------------- |
-| `--llng-ini` | `DM_LLNG_INI` | `/etc/lemonldap-ng/lemonldap-ng.ini` | LemonLDAP::NG config path |
+| CLI                      | Env                       | Default                              | Description                                                                                        |
+| ------------------------ | ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `--llng-ini`             | `DM_LLNG_INI`             | `/etc/lemonldap-ng/lemonldap-ng.ini` | LemonLDAP::NG config path                                                                          |
+| `--llng-username-header` | `DM_LLNG_USERNAME_HEADER` |                                      | Header LLNG exports with the login, published as `req.userName` (see [llng](plugins/auth/llng.md)) |
 
 #### `core/auth/openidconnect`
 
-| CLI                    | Env                     | Default | Description              |
-| ---------------------- | ----------------------- | ------- | ------------------------ |
-| `--oidc-server`        | `DM_OIDC_SERVER`        |         | OIDC server URL          |
-| `--oidc-client-id`     | `DM_OIDC_CLIENT_ID`     |         | OIDC Client ID           |
-| `--oidc-client-secret` | `DM_OIDC_CLIENT_SECRET` |         | OIDC Client Secret       |
-| `--base-url`           | `DM_BASE_URL`           |         | Public URL for callbacks |
+| CLI                     | Env                      | Default | Description                                                                             |
+| ----------------------- | ------------------------ | ------- | --------------------------------------------------------------------------------------- |
+| `--oidc-server`         | `DM_OIDC_SERVER`         |         | OIDC server URL                                                                         |
+| `--oidc-client-id`      | `DM_OIDC_CLIENT_ID`      |         | OIDC Client ID                                                                          |
+| `--oidc-client-secret`  | `DM_OIDC_CLIENT_SECRET`  |         | OIDC Client Secret                                                                      |
+| `--oidc-username-claim` | `DM_OIDC_USERNAME_CLAIM` | `sub`   | Claim naming the caller, published as `req.userName` (see [OIDC](plugins/auth/oidc.md)) |
+| `--base-url`            | `DM_BASE_URL`            |         | Public URL for callbacks                                                                |
+
+#### `core/bcl`
+
+Back-Channel Logout: a logout performed at the provider ends the session here
+on the next request. Needs `core/storage`, and refuses to start without it —
+see [Back-Channel Logout](plugins/auth/back-channel-logout.md).
+
+| CLI               | Env                | Default  | Description                 |
+| ----------------- | ------------------ | -------- | --------------------------- |
+| `--bcl-retention` | `DM_BCL_RETENTION` | `604800` | Seconds a tombstone is kept |
 
 ### Authorization Plugins
 
+#### Common to every authorization plugin
+
+| CLI                       | Env                        | Default    | Description                                                                                                                                                                                                                       |
+| ------------------------- | -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-unresolved-user` | `DM_AUTHZ_UNRESOLVED_USER` | `deny`     | What an authenticated identity the plugin cannot resolve means: `deny` refuses the operation, `allow` lets it through with a warning                                                                                              |
+| `--authz-identity`        | `DM_AUTHZ_IDENTITY`        | `req.user` | Which value rules are keyed on: `req.user`, this server's identifier for the caller, or `req.userName`, the caller under a name a person would use. See [what a rule is keyed on](plugins/auth/README.md#what-a-rule-is-keyed-on) |
+| `--authz-for`             | `DM_AUTHZ_FOR`             |            | The authentication plugins, by instance name, whose requests the plugin judges; unset, every authenticated request. Meant for a plugin's own overrides: `{"authz_for":["oidc"]}`                                                  |
+| `--authz-combine`         | `DM_AUTHZ_COMBINE`         | `false`    | Let two plugins judging the LDAP operations of the same requests start together, as an AND                                                                                                                                        |
+
+`--authz-unresolved-user` is read by the plugins that resolve an identity
+before judging it — `core/auth/authzPerBranch` and `core/auth/authzLinid1`.
+`core/auth/authzPerRoute` matches the identity as it stands and
+`core/auth/authzDynamic` judges a token, so neither resolves anything and
+neither reads it. A value other than `deny` or `allow` is refused at startup.
+
+An **anonymous** request is not this case: it carries no identity, and every
+authorization plugin skips it as before. This is about a caller the
+authenticator admitted whose identity the authorization model cannot place —
+`authzLinid1` looking up a `uid` that does not exist, typically because the
+authenticator publishes something else. `allow` is the behaviour every plugin
+had before 0.8.3, and it is an open door where `authzLinid1` is loaded: see
+[the note](upgrading.md#an-identity-that-does-not-resolve-is-refused).
+
+`--authz-for` and `--authz-combine` say how plugins loaded together compose:
+without them, two plugins judging the LDAP operations of the same requests
+are refused at startup — see [several authorization
+plugins](plugins/auth/README.md#several-authorization-plugins).
+
+`--authz-for` takes one name per occurrence: repeat it
+(`--authz-for oidc --authz-for authToken`), or give the environment variable
+a list (`DM_AUTHZ_FOR="oidc authToken"`). A second word after the value —
+`--authz-for oidc authToken` — is refused rather than dropped, as it is after
+every option taking a list.
+
+`--authz-identity` is a different question, and the paragraphs above are not
+about it: `core/auth/authzPerRoute` and the SCIM base map read it as well,
+since a route rule and the base a SCIM operation is served from are keyed on
+whichever of the two names it selects. A value other than `req.user` or
+`req.userName` is refused at startup.
+
 #### `core/auth/authzPerBranch`
 
-| CLI                            | Env                             | Default                                          | Description                 |
-| ------------------------------ | ------------------------------- | ------------------------------------------------ | --------------------------- |
-| `--authz-per-branch-config`    | `DM_AUTHZ_PER_BRANCH_CONFIG`    | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON) |
-| `--authz-per-branch-cache-ttl` | `DM_AUTHZ_PER_BRANCH_CACHE_TTL` | `60`                                             | Cache TTL (seconds)         |
+| CLI                               | Env                                | Default                                          | Description                                                                                                                                                                   |
+| --------------------------------- | ---------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-per-branch-config`       | `DM_AUTHZ_PER_BRANCH_CONFIG`       | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                   |
+| `--authz-per-branch-cache-ttl`    | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`    | `60`                                             | Cache TTL (seconds)                                                                                                                                                           |
+| `--authz-filter-attached-entries` | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES` | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch` and `authzLinid1`; does nothing under `authzDynamic`. |
+
+#### `core/auth/authzScope`
+
+| CLI                    | Env                     | Default | Description                                                                                                                                                    |
+| ---------------------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-scope-source` | `DM_AUTHZ_SCOPE_SOURCE` |         | The plugin, by instance name, that describes a caller's scope when several judge them; unset, the first loaded. See [authz-scope](plugins/auth/authz-scope.md) |
 
 #### `core/auth/authzPerRoute`
 
@@ -384,6 +447,19 @@ Automatically creates/updates/deletes applicative account entries when users are
 
 Web access logging plugin. No configuration options - just add the plugin to enable access logs.
 
+#### `core/storage`
+
+Keyed storage with a deadline, for the plugins that need to keep something —
+see [Storage](plugins/utilities/storage.md).
+
+| CLI                           | Env                            | Default              | Description                            |
+| ----------------------------- | ------------------------------ | -------------------- | -------------------------------------- |
+| `--storage-backend`           | `DM_STORAGE_BACKEND`           |                      | `ldap` or `file`; required             |
+| `--storage-sweep-interval`    | `DM_STORAGE_SWEEP_INTERVAL`    | `600`                | Seconds between two expiry passes      |
+| `--storage-ldap-base`         | `DM_STORAGE_LDAP_BASE`         |                      | Branch the `ldap` backend writes to    |
+| `--storage-ldap-object-class` | `DM_STORAGE_LDAP_OBJECT_CLASS` | `applicationProcess` | Object class of the entries it writes  |
+| `--storage-file-directory`    | `DM_STORAGE_FILE_DIRECTORY`    |                      | Directory the `file` backend writes to |
+
 #### `core/configApi`
 
 Exposes API configuration at `/api/v1/config` for client applications. Returns available features, schemas, and endpoints. No configuration options.

package/docs/usage/plugins/README.md

@@ -21,13 +21,14 @@ LDAP entity management:
 
 Secure API access:
 
-| Plugin                 | Description                              |
-| ---------------------- | ---------------------------------------- |
-| [token](auth/token.md) | Bearer token authentication              |
-| [totp](auth/totp.md)   | TOTP authentication (time-based codes)   |
-| [hmac](auth/hmac.md)   | HMAC-SHA256 signing for backend services |
-| [llng](auth/llng.md)   | LemonLDAP::NG SSO integration            |
-| [oidc](auth/oidc.md)   | OpenID Connect / OAuth 2.0               |
+| Plugin                                             | Description                                    |
+| -------------------------------------------------- | ---------------------------------------------- |
+| [token](auth/token.md)                             | Bearer token authentication                    |
+| [totp](auth/totp.md)                               | TOTP authentication (time-based codes)         |
+| [hmac](auth/hmac.md)                               | HMAC-SHA256 signing for backend services       |
+| [llng](auth/llng.md)                               | LemonLDAP::NG SSO integration                  |
+| [oidc](auth/oidc.md)                               | OpenID Connect / OAuth 2.0                     |
+| [back-channel-logout](auth/back-channel-logout.md) | Honour a logout performed at the OIDC provider |
 
 ## Authorization Plugins
 
@@ -61,10 +62,11 @@ Connect to external systems:
 
 ## Utility Plugins
 
-| Plugin                          | Description        |
-| ------------------------------- | ------------------ |
-| [static](utilities/static.md)   | Static file server |
-| [weblogs](utilities/weblogs.md) | HTTP logging       |
+| Plugin                          | Description                   |
+| ------------------------------- | ----------------------------- |
+| [static](utilities/static.md)   | Static file server            |
+| [weblogs](utilities/weblogs.md) | HTTP logging                  |
+| [storage](utilities/storage.md) | Keyed storage with a deadline |
 
 ## Plugin Dependencies
 
@@ -79,10 +81,13 @@ core/ldap/externalUsersInGroups
 
 core/auth/authzPerBranch
   └─ requires: An authentication plugin
+
+core/bcl
+  └─ requires: core/storage (refuses to start without it)
 ```
 
 See [the complete dependencies matrix](../../plugin-development/dependencies.md).
 
 ## Load Order
 
-Authentication plugins are loaded first to secure API endpoints. The order is defined in `src/plugins/priority.json`.
+Authentication plugins are loaded first, so their middleware sits ahead of the routes it guards. The list also carries the plugins other plugins depend on, which have to be registered before the batch their consumers land in — `core/storage` is one. The order is defined in `src/plugins/priority.json`.

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

@@ -12,6 +12,135 @@ LDAP-Rest provides multiple authentication plugins to secure API access. These p
 | [LemonLDAP::NG](llng.md)  | `core/auth/llng`          | Integration with LemonLDAP::NG SSO               |
 | [OpenID Connect](oidc.md) | `core/auth/openidconnect` | OAuth 2.0 / OpenID Connect authentication        |
 
+## What a rule is keyed on
+
+Authorization rules name a caller, and each authenticator has its own idea
+of what a caller is called. Every one of them publishes the caller twice:
+
+| Authenticator             | `req.user`                          | `req.userName`                           |
+| ------------------------- | ----------------------------------- | ---------------------------------------- |
+| `core/auth/token`         | the name given in `--auth-token`    | the same                                 |
+| `core/auth/totp`          | the name given in `--auth-totp`     | the same                                 |
+| `core/auth/hmac`          | the service name from `--auth-hmac` | the same                                 |
+| `core/auth/llng`          | LLNG's `whatToTrace`                | `--llng-username-header`, or the same    |
+| `core/auth/openidconnect` | the OIDC `sub`                      | `--oidc-username-claim` (default: `sub`) |
+| `core/auth/authzDynamic`  | the token's tenant                  | the same                                 |
+
+`req.user` is this server's identifier for the caller; `req.userName` is the
+caller under a name a person would use. `--authz-identity` says which one is
+keyed on by `core/auth/authzPerBranch`, `core/auth/authzLinid1`,
+`core/auth/authzPerRoute` and the SCIM base map — every plugin that names a
+caller in its configuration:
+
+```bash
+--authz-identity req.user        # the default: every existing rule is unchanged
+--authz-identity req.userName    # rules written on logins
+```
+
+The second is what makes a rule portable. Under OpenID Connect the `sub` is
+opaque — `auth0|…`, a UUID — so rules keyed on it have to be looked up per
+administrator and rewritten when the provider changes; keyed on
+`preferred_username` they read as the logins they are.
+
+A value other than these two is refused at startup. When the option asks for
+`req.userName` and the authenticator published none, permissions are read for
+`req.user` and a warning says so once — a rule that silently stops matching
+is worse than one that refuses.
+
+At startup each authenticator logs what it will publish, and each
+authorization plugin whose configured identities none of them can produce
+says so: token, TOTP and HMAC names are in the configuration, and an
+identity provider's claims are not, in which case the line says it cannot be
+checked before a login rather than staying silent.
+
+## Several authorization plugins
+
+Every plugin that judges LDAP operations — `core/auth/authzPerBranch`,
+`core/auth/authzLinid1`, `core/auth/authzDynamic` — registers the same hooks,
+and all of them run: loaded together, they compose as an **AND**, and the
+first refusal wins. The per-caller read filter (`ldapsearchfilter`) is one of
+those hooks: two plugins there compose as an intersection, which is the same
+AND. That is sound when it is meant. When it is not, it is a
+refusal nobody can explain: `authzPerBranch` beside `authzDynamic` judges a
+machine token by a branch configuration written for administrators, finds
+no entry for the tenant, and refuses a write the token's own ACLs grant.
+
+The AND needs no second plugin to bite. `--authz-per-branch-config` has a
+default — read everywhere, write nowhere — so a lone `authzPerBranch` judges
+**every** authenticated identity, whatever authenticated it: a token that no
+rule names reads, and every write it attempts is refused.
+
+### Whose requests a plugin judges
+
+The dispatcher records which authentication plugins vouched for a request,
+by instance name, in `req.authenticators`. An authorization plugin given
+`authz_for` judges the requests of those plugins and skips the others:
+
+```bash
+--plugin core/auth/authzDynamic
+--plugin 'core/auth/openidconnect:oidc:{"auth_path_prefix":"/api/admin"}'
+--plugin 'core/auth/authzPerBranch:authzPerBranch:{"authz_for":["oidc"]}'
+```
+
+Here the tokens are held to their own ACLs, and the administrators signed in
+through OpenID Connect to the branch configuration: no request is judged by
+both. Unset, `authz_for` means every authenticated request — what every
+plugin did before the option existed. It is read by `authzPerBranch`,
+`authzLinid1` and `authzPerRoute`; `authzDynamic` judges the requests
+carrying its own tokens, and no others, whatever the option says — an
+`authz_for` of its own there is said at startup rather than ignored in
+silence.
+
+Two cases stay apart:
+
+- a request **another** population's authenticator vouched for is skipped —
+  it is not this model's business;
+- a request of **this** population whose identity does not resolve is
+  refused — a configuration error, not an absence of one
+  (`--authz-unresolved-user`).
+
+A request carrying an identity that no authenticator vouched for is judged:
+"not mine" is never inferred from an absence. A plugin that only stepped
+aside — `authzDynamic` letting a request through on
+`--authz-dynamic-bypass` — did not vouch for it and is not recorded.
+
+### What is refused at startup
+
+- Two plugins judging LDAP operations for the same authenticator's requests
+  — two branch-level plugins with no `authz_for`, or a branch-level plugin
+  judging `authzDynamic`'s tokens — are refused, with both names, unless
+  `--authz-combine` says the AND is meant. `authzPerRoute` registers no LDAP
+  hook and is never part of it: route plus branch, and route plus token, are
+  deliberate ANDs on identities each side can name.
+- An `authz_for` naming no loaded authentication plugin is refused: the
+  plugin would judge nobody, which reads as a working configuration. A
+  server-wide `--authz-for` that no loaded plugin reads — only
+  `authzDynamic` there — is said: it scopes nothing.
+- Two plugins whose populations only meet through two authenticators on the
+  same path prefix — a request presenting both credentials is judged by
+  both — are said, not refused: asking for two credentials is a decision
+  already.
+
+A host that assembles the server itself — `registerPlugin` after `ready`,
+rather than `--plugin` — gets the same checks, as each plugin arrives: the
+refusal comes out of `registerPlugin`, before any of the plugin's routes or
+hooks exist. An arriving plugin is judged against what is already there, so
+the authentication plugins an `authz_for` or `--authz-scope-source` names
+are registered before the plugin naming them.
+
+### What the log says
+
+At startup, one line per plugin names the hooks it takes part in and whose
+requests it judges — `every authenticated request (authToken, oidc)` when
+`authz_for` is unset, so a model judging an authenticator nobody wrote it
+for is visible before a request arrives. When a hook refuses, the log line
+names the plugin that refused; the 403 body does not, as it never discloses
+the model.
+
+With two plugins combined on purpose, `--authz-filter-attached-entries` only
+broadens a listing while both honour it — both do, being built on the same
+base class, but nothing obliges a third implementation to.
+
 ## Authorization Plugins
 
 | Method                                          | Plugin                     | Description                  |

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

@@ -44,6 +44,44 @@ node lib/bin/index.js \
 | `--authz-dynamic-config-attribute` | `DM_AUTHZ_DYNAMIC_CONFIG_ATTRIBUTE` | `description`  | Attribute holding the JSON ACL document                               |
 | `--authz-dynamic-tenant-attribute` | `DM_AUTHZ_DYNAMIC_TENANT_ATTRIBUTE` | `cn`           | Attribute from which `req.user` is read                               |
 | `--authz-dynamic-reload-endpoint`  | `DM_AUTHZ_DYNAMIC_RELOAD_ENDPOINT`  | `false`        | Register `POST /api/v1/authz-dynamic/reload` for manual cache refresh |
+| `--authz-dynamic-bypass`           | `DM_AUTHZ_DYNAMIC_BYPASS`           | _(empty)_      | Who may reach the directory without one of these tokens (see below)   |
+
+### Loading this plugin beside another authenticator
+
+The dispatcher runs every authentication plugin claiming a request's path,
+so a request can arrive here already identified by another one. Until 0.9.0
+this plugin stepped aside whenever that happened, and the token ACLs were
+then applied to nothing: with `core/auth/token` loaded beside it, a static
+token reached the whole directory as an unscoped administrator — or was
+refused for lacking a dynamic token, depending on which plugin had been
+registered first.
+
+The ACLs now apply to whatever token the request carries, whoever else
+identified it, and anything allowed past them without a token is named:
+
+| `--authz-dynamic-bypass` | Effect                                                                                              |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| _(empty, the default)_   | Nobody. A request must carry one of these tokens                                                    |
+| `any-authenticated`      | Anything another plugin authenticated — the behaviour before 0.9.0                                  |
+| `trusted-proxy`          | A request from a trusted proxy **that named a caller** (`req.trustedProxy` and `req.proxyAuthUser`) |
+| any other value          | The identity another authenticator publishes in `req.user`, e.g. a name from `--auth-token`         |
+
+Values combine: `--authz-dynamic-bypass trusted-proxy --authz-dynamic-bypass ops-admin`.
+
+`trusted-proxy` requires the proxy to have named someone. `trustedProxy`
+marks the _address_ it trusts and fills `proxyAuthUser` only when the
+request carried the authentication header it expects, so accepting the mark
+alone would hand the whole directory to every host of the `--trusted-proxy`
+range — `10.0.0.0/8` being all of it.
+
+A bypassed request carries **no** token, so no ACL is enforced on it — that
+is what a bypass is. Each one is logged at `info` with the reason that let it
+through, and a configuration loading this plugin beside another
+authenticator says so once at startup.
+
+The answer no longer depends on registration order: when the bypass names an
+identity another plugin has not published yet, the verdict waits until every
+authenticator has run.
 
 ## Token entry shape
 
@@ -148,6 +186,10 @@ ACL, the client is cryptographically constrained to its own SCIM subtree.
   deploy cleartext secrets in production.
 - **Timing**: comparisons run through `crypto.timingSafeEqual` or a buffer
   wrapper, preventing timing oracles on the secret.
+- **Composition**: loading another authenticator on the same paths means a
+  request can arrive already identified. It is still checked against the
+  token it carries; what may pass without one is `--authz-dynamic-bypass`,
+  and nothing else.
 - **Scope escape**: the authz hooks check every LDAP operation's DN against
   the token's ACL. The active token is carried via `AsyncLocalStorage`, so it
   applies even to plugins that do not thread `req` down to `ldapActions`.

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

@@ -60,6 +60,38 @@ No configuration file needed - permissions are read from LDAP. Simply load the p
 
 The plugin caches permissions for 5 minutes by default. This is hardcoded but can be modified in the source if needed.
 
+### The identity has to be a `uid`
+
+The plugin resolves `req.user` by searching
+`(<ldap_user_main_attribute>=<identity>)` under `--ldap-base`, so it only
+works behind an authenticator that publishes what the directory calls a user:
+
+| Authenticator             | `req.user`                       | Resolves here                          |
+| ------------------------- | -------------------------------- | -------------------------------------- |
+| `core/auth/token`         | the name given in `--auth-token` | only if that name is a `uid`           |
+| `core/auth/totp`          | the name given in `--auth-totp`  | only if that name is a `uid`           |
+| `core/auth/hmac`          | the service name                 | usually not                            |
+| `core/auth/llng`          | LLNG's `whatToTrace`             | when it traces the `uid`               |
+| `core/auth/openidconnect` | the OIDC `sub`                   | **no** — an opaque provider identifier |
+
+An identity that does not resolve is **refused** (403), and the refusal is
+logged with the plugin's name. Until 0.9.0 it was let through instead, which
+made this pairing an open door rather than a misconfiguration; see
+[the note](../../upgrading.md#an-identity-that-does-not-resolve-is-refused)
+and `--authz-unresolved-user` for the transition.
+
+Both answers are cached for the plugin's TTL (5 minutes), negatives
+included, so a mismatch does not turn every request into a directory search.
+The TTL cuts both ways: an identity added to the directory after being
+refused waits it out, and an administrator whose **own entry is renamed or
+moved** keeps resolving to the former DN — where no organization names them,
+so their own operations are refused. A rename or a delete performed through
+this server drops what was resolved; a change made directly in the directory
+waits out the TTL.
+
+`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.
+
 ## Permission Resolution
 
 For each LDAP operation, the plugin: