ldap-rest 0.8.2 → 0.10.0

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

@@ -15,20 +15,60 @@ whichever authorization plugin is in force.
 --plugin core/auth/authzScope
 ```
 
-It has no options. It answers through whichever loaded plugin carries the
-`authz` role _and_ can say who may do what where — one implementing
-`resolveUser`, `getAuthorizedBranches` and `getUserPermissions`. Both
+It answers through a loaded plugin that carries the `authz` role _and_ can
+say who may do what where — one implementing `resolveUser`,
+`getAuthorizedBranches` and `getUserPermissions`. Both
 [authz-linid1](authz-linid1.md) and [authz-per-branch](authz-per-branch.md)
 do, and this endpoint works with either without knowing which.
 
-The role alone is not enough. [authz-per-route](authz-per-route.md) gates URLs
-and [authz-dynamic](authz-dynamic.md) reads a token: both carry the `authz`
-role and implement none of those three methods, so this endpoint passes them
-over — loading one beside a branch-level plugin changes the answer not at all.
-A server whose only authorization plugin is one of those has nothing to
-describe a scope with, and the answer is the unrestricted one shown below: a
-client built on it shows every button, and a refusal, when it comes, comes from
-the route or the token rather than from the scope.
+| CLI                    | Env                     | Default | Description                                                   |
+| ---------------------- | ----------------------- | ------- | ------------------------------------------------------------- |
+| `--authz-scope-source` | `DM_AUTHZ_SCOPE_SOURCE` |         | The plugin, by instance name, that describes a caller's scope |
+
+### Which plugin answers
+
+The caller is resolved under the name the hooks key on — `req.user`, or
+`req.userName` with `--authz-identity req.userName` — so the scope described
+is the one enforced.
+
+Only a plugin that judges the caller answers for them: one scoped with
+`authz_for` to other authentication plugins is not this caller's model, and
+is passed over (see [several authorization
+plugins](README.md#several-authorization-plugins)).
+
+When more than one judges the caller — two branch-level plugins combined with
+`--authz-combine` — the hooks apply both and this endpoint can describe only
+one. `--authz-scope-source` names it. Without it, the first loaded answers,
+and for plugins outside the priority list that is import order, which nobody
+chose: the server says so at startup, and the answer lists every plugin
+judging the caller under `sources`, the one it comes from under `source`. A
+name that is not a loaded plugin able to describe a scope is refused at
+startup.
+
+### When nothing can describe the scope
+
+[authz-per-route](authz-per-route.md) gates URLs and
+[authz-dynamic](authz-dynamic.md) reads a token: both carry the `authz` role,
+neither resolves a user or a branch. When they judge the caller and no
+branch-level plugin does, no model can say what the caller may do, and the
+answer says that rather than guessing:
+
+```json
+{
+  "user": "alice",
+  "unrestricted": false,
+  "described": false,
+  "source": null,
+  "sources": ["authzPerRoute"],
+  "branches": [],
+  "entities": []
+}
+```
+
+This endpoint used to answer `unrestricted: true` with `create: true` on
+every entity there — an authorization judgement handed to a client that acts
+on it, while the route or the token refused. A client that reads an entity
+missing from `entities` as not creatable offers nothing.
 
 ## Endpoint
 
@@ -40,6 +80,9 @@ GET /api/v1/authz/scope
 {
   "user": "uid=alice,ou=users,dc=example,dc=com",
   "unrestricted": false,
+  "described": true,
+  "source": "authzLinid1",
+  "sources": ["authzLinid1"],
   "branches": [
     {
       "dn": "ou=Sales,ou=organization,dc=example,dc=com",
@@ -77,13 +120,16 @@ is where a new organization goes when the client names no parent. A local admini
 `create: false` for organizations, and creates sub-organizations under their own
 node by naming it as `parentDn`.
 
-With no authorization plugin loaded the server grants everything, and the
-answer says so:
+With no authorization plugin judging the caller the server grants
+everything, and the answer says so:
 
 ```json
 {
   "user": "alice",
   "unrestricted": true,
+  "described": true,
+  "source": null,
+  "sources": [],
   "branches": [],
   "entities": [
     { "name": "users", "base": "ou=users,dc=example,dc=com", "create": true }
@@ -93,9 +139,21 @@ answer says so:
 
 ## Errors
 
-| Status | When                                                          |
-| ------ | ------------------------------------------------------------- |
-| `401`  | No authenticated user, or a user the directory cannot resolve |
+| Status | When                                                                                        |
+| ------ | ------------------------------------------------------------------------------------------- |
+| `401`  | No authenticated user while any authorization plugin is loaded, or a user it cannot resolve |
+
+An anonymous caller is refused as soon as anything authorizes: every
+authorization plugin skips a request without an identity, so nothing would
+judge them and the answer would be `unrestricted: true` — more than an
+identified caller of the same server is told. A server loading no
+authorization plugin at all answers `unrestricted` to anyone, anonymous
+included, which is what it does.
+
+An identity that names **several** entries — the same `uid` in two branches of
+a directory without the `unique` overlay, which `authzLinid1` refuses with
+`AmbiguousIdentityError` — is answered `403`, not `401`: the caller cannot be
+told apart from the homonym, so no scope can be described for them.
 
 ## See also
 

package/docs/usage/plugins/auth/back-channel-logout.md

@@ -0,0 +1,86 @@
+# Back-Channel Logout
+
+Honouring a logout the provider performed elsewhere.
+
+## Overview
+
+When someone logs out at the OpenID Provider — or an administrator ends their
+sessions — the provider sends a **logout token** to every application that
+asked for one. Without it, an application keeps honouring its own cookie: the
+session stays alive until it expires on its own, which is exactly what a
+logout is supposed to prevent.
+
+`core/bcl` records what such a token killed, and `core/auth/openidconnect`
+asks, on every request, whether the session it holds is still alive.
+
+**Nothing here stores a session.** A logout token only leaves a _tombstone_
+saying that one `sid`, or every session of one `sub`, is dead. Sessions stay
+in their cookie, and the storage holds only what died — which is what keeps
+it small.
+
+## Configuration
+
+```bash
+--plugin core/auth/openidconnect \
+--plugin core/storage --storage-backend file --storage-file-directory /var/lib/ldap-rest/storage \
+--plugin core/bcl --bcl-retention 604800
+```
+
+| Option            | Environment        | Default  | Description                 |
+| ----------------- | ------------------ | -------- | --------------------------- |
+| `--bcl-retention` | `DM_BCL_RETENTION` | `604800` | Seconds a tombstone is kept |
+
+Where the marks live, and how often expired ones are reclaimed, belongs to
+[`core/storage`](../utilities/storage.md) — `core/bcl` keeps only the policy.
+
+At the provider, register the back-channel logout URI:
+
+```
+https://ldap-rest.example.com/backchannel-logout
+```
+
+## Retention
+
+A tombstone has to outlive the session it kills, or a cookie older than the
+mark would be honoured again. The default matches `express-openid-connect`'s
+own seven-day session; shorten it only alongside the session lifetime.
+
+Expiry is enforced when the mark is read, not only when the sweeper passes,
+so a late sweeper never keeps out someone who has since logged in again.
+
+## `core/bcl` Refuses to Start Without Storage
+
+`core/storage` must be loaded and `--storage-backend` set, or the plugin
+throws at startup.
+
+That is deliberate. A logout check that quietly does nothing would leave
+every session outliving the logout that closed it, and nothing would say so.
+For a feature that can be skipped, a warning is the right answer; for this
+one, a refusal to start is the honest failure.
+
+The refusal answers for the configuration, not for the order it is written
+in. `core/bcl` declares `core/storage` as a dependency, so a configuration
+naming only `core/bcl` loads the store anyway; and `core/storage` is in the
+priority list, so one that names both gets a single instance whichever comes
+first.
+
+## What a Login Forgets
+
+A mark on the `sub` kills every session of that person. Left in place it
+would also kill the sessions created _after_ it, for the whole retention —
+so a successful login clears the marks matching its own claims.
+
+This has a consequence worth knowing, which the SDK's own default shares: a
+login also revives sessions that a "log out everywhere" token killed without
+naming a `sid`.
+
+## Failures Are Not Swallowed
+
+If the store cannot record a tombstone, the provider is answered `400` rather
+than `204`. A provider retries a `400`; a `204` tells it a logout was honoured
+that nothing kept.
+
+## See Also
+
+- [Storage](../utilities/storage.md) — where the marks live
+- [OpenID Connect](oidc.md)

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

@@ -15,6 +15,35 @@ Integration with [LemonLDAP::NG](https://lemonldap-ng.org/) (LLNG) Web SSO solut
 DM_LLNG_INI="/etc/lemonldap-ng/lemonldap-ng.ini"
 ```
 
+## Rules that name nobody
+
+The plugin serves a request only when the handler named a user. A LemonLDAP::NG
+location rule set to `skip` makes the handler return at once — no session
+read, no `Lm-Remote-User` written — and such a request is refused with 401
+rather than served with no identity: every authorization plugin skips its
+check when a request carries no identity, so "no authentication on this path"
+would have become "authenticated, and scoped by nobody".
+
+Serve such a path from a virtual host this plugin does not guard, or scope
+the plugin with `auth_path_prefix` so the path falls outside it.
+
+The identity header is read whatever case the handler wrote it in, and
+whatever the client sent under that name is dropped before the handler runs:
+only the handler may name the caller.
+
+`req.user` is what `whatToTrace` traces, which is often a mail or a display
+name. `--llng-username-header` names a second header LemonLDAP::NG exports
+carrying the login, published as `req.userName`; with
+`--authz-identity req.userName`, rules are then written on logins. Export it
+from the LLNG configuration as you would any other header.
+
+Whatever the request carried under that name is dropped before the handler
+runs, exactly as the identity header is: a rule can be keyed on
+`req.userName`, so a client supplying it would otherwise take over the
+identity that rule names. The consequence is that the value must come from
+the handler — a header set by an upstream proxy does not survive, and would
+only have been trustworthy if that proxy stripped the client's copy itself.
+
 ## Prerequisites
 
 1. **LemonLDAP::NG Handler**: The `lemonldap-ng-handler` npm package (optional dependency)

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

@@ -35,6 +35,56 @@ Install the optional dependency:
 npm install express-openid-connect
 ```
 
+## Scope
+
+Like every other authentication plugin, this one registers with the server's
+authentication dispatcher, so `auth_path_prefix` says which paths it guards:
+
+```bash
+--plugin 'core/auth/openidconnect:oidc:{"auth_path_prefix":"/api/admin"}'
+```
+
+Until 0.9.0 the option was accepted and ignored — the plugin mounted its own
+middleware and guarded the whole server — and the layers it mounted kept
+their registration order, so a route plugin loading before it was served
+without a session and an authorization plugin loading after it judged rules
+before `req.user` existed. See
+[the note](../../upgrading.md#openid-connect-honours-auth_path_prefix).
+
+Its own routes come with it: `/login`, `/logout`, `/callback` and
+`/backchannel-logout` are claimed whatever the scope, so the provider can
+always reach the callback and post a logout token, and a catch-all
+authentication never answers them with a 401.
+
+Two instances are supported — `auth()` builds a fresh router per instance —
+but `--base-url` and the callback path are global, so both share one
+redirect URI. Scope by prefix, not by provider, unless you also front them
+with different base URLs.
+
+## The identity it publishes
+
+`req.user` is the OIDC `sub` — an opaque provider identifier, `auth0|…` or a
+UUID — which is what authorization rules are keyed on by default, and what
+nobody can write a rule for without looking it up per administrator.
+
+`--oidc-username-claim` names the claim published as `req.userName`:
+
+```bash
+--oidc-username-claim preferred_username
+```
+
+Ask the provider for the scope that carries it (`profile`, or `email` for
+`email`), then key the authorization plugins on it with
+`--authz-identity req.userName`. A session missing the configured claim falls
+back to the `sub`, with a warning naming the claim.
+
+## What an unauthenticated request receives
+
+The library's own answer: a browser is redirected to the provider, an API
+client (`Accept: application/json`) receives 401. Every other authentication
+plugin in this repository answers JSON 401 throughout — the difference is
+kept because it is what makes a login work at all.
+
 ## How It Works
 
 1. Uses `express-openid-connect` for OAuth2/OIDC flow
@@ -163,5 +213,7 @@ npm install express-openid-connect
 
 ## See Also
 
+- [Back-Channel Logout](back-channel-logout.md) — honouring a logout the
+  provider performed elsewhere
 - [OpenID Connect Specification](https://openid.net/connect/)
 - [express-openid-connect](https://github.com/auth0/express-openid-connect)

package/docs/usage/plugins/ldap/on-change.md

@@ -1,10 +1,7 @@
 # LDAP onChange Plugin
 
-Monitor LDAP attribute changes and trigger hooks for specific attributes.
-
-## Overview
-
-The `onChange` plugin watches for LDAP modifications and generates specialized hooks when configured attributes change. This enables reactive integrations with external systems (mail servers, quota managers, etc.).
+Publish the state of an entry before and after each write made through
+LDAP-Rest, and hooks for the attributes other plugins follow.
 
 ## Configuration
 
@@ -14,305 +11,75 @@ The `onChange` plugin watches for LDAP modifications and generates specialized h
 --quota-attribute mailQuota
 ```
 
-**Environment Variables:**
-
-```bash
-DM_MAIL_ATTRIBUTE="mail"
-DM_QUOTA_ATTRIBUTE="mailQuota"
-```
-
-## Generated Hooks
-
-The plugin generates hooks based on configured attributes:
-
-| Config Parameter    | Generated Hook      | Parameters                       |
-| ------------------- | ------------------- | -------------------------------- |
-| `--mail-attribute`  | `onLdapMailChange`  | `(dn, oldMail, newMail)`         |
-| `--quota-attribute` | `onLdapQuotaChange` | `(dn, mail, oldQuota, newQuota)` |
-
-Generic hook for any change:
-
-- `onLdapChange` - `(dn, changes)` where `changes` is `Record<attr, [oldValue, newValue]>`
-
-## How It Works
-
-1. **Hooks into LDAP modify operations** via `ldapUsersmodify` and `ldapGroupsmodify` hooks
-2. **Detects attribute changes** by comparing old and new values
-3. **Triggers specialized hooks** for configured attributes
-4. **Provides old and new values** to downstream hooks
-
-## Use Cases
-
-### Mail Server Synchronization
-
-When user email changes, update external mail server:
-
-```javascript
-// In another plugin
-hooks: {
-  onLdapMailChange: async (dn, oldMail, newMail) => {
-    await mailServer.renameAccount(oldMail, newMail);
-    console.log(`Renamed mail account: ${oldMail} → ${newMail}`);
-  };
-}
-```
-
-### Quota Management
-
-When quota changes, update mail server quota:
-
-```javascript
-hooks: {
-  onLdapQuotaChange: async (dn, mail, oldQuota, newQuota) => {
-    await mailServer.setQuota(mail, newQuota);
-    console.log(`Updated quota for ${mail}: ${oldQuota} → ${newQuota}`);
-  };
-}
-```
-
-### Generic Change Tracking
-
-Track all attribute changes:
-
-```javascript
-hooks: {
-  onLdapChange: async (dn, changes) => {
-    for (const [attr, [oldVal, newVal]] of Object.entries(changes)) {
-      console.log(`${dn}: ${attr} changed from ${oldVal} to ${newVal}`);
-    }
-  };
-}
-```
-
-## Examples
-
-### Example 1: Mail Attribute Monitoring
-
-```bash
---plugin core/ldap/onChange \
---plugin core/ldap/flatGeneric \
---ldap-flat-schema ./schemas/users.json \
---mail-attribute mail
-```
-
-When a user's mail attribute changes via API:
-
-```bash
-PUT /api/v1/ldap/users/jdoe
-{
-  "replace": {
-    "mail": "john.doe@newdomain.com"
-  }
-}
-```
-
-The `onLdapMailChange` hook fires with:
-
-- `dn`: `"uid=jdoe,ou=users,dc=example,dc=com"`
-- `oldMail`: `"jdoe@olddomain.com"`
-- `newMail`: `"john.doe@newdomain.com"`
-
-### Example 2: Multiple Attributes
-
-```bash
---plugin core/ldap/onChange \
---mail-attribute mail \
---quota-attribute mailQuota
-```
-
-When both attributes change:
+## Hooks
 
-```bash
-PUT /api/v1/ldap/users/jdoe
-{
-  "replace": {
-    "mail": "jdoe@company.com",
-    "mailQuota": "5000000000"
-  }
-}
-```
+`onLdapEntryChange(dn, before, after, context)` fires after every add,
+modify, rename and delete, with the entry as the directory held it on each
+side:
 
-Both hooks fire:
+| Operation | `before`                 | `after`                  |
+| --------- | ------------------------ | ------------------------ |
+| add       | `null`                   | the new entry            |
+| modify    | the entry before         | the entry after          |
+| rename    | the entry, at its old DN | the entry, at its new DN |
+| delete    | the entry before         | `null`                   |
 
-1. `onLdapMailChange(dn, "old@mail.com", "jdoe@company.com")`
-2. `onLdapQuotaChange(dn, "jdoe@company.com", "1000000000", "5000000000")`
+`dn` is the entry's DN after the write, its old one on a delete. `context`
+says who made the write, and through which door:
 
-### Example 3: Generic Change Listener
+- `actor`: the caller's `userName`, or its `user` when it has none;
+- `requestId`: generated, the same for every write of one request;
+- `source`: `scim` for the SCIM API, `rest` otherwise.
 
-```bash
---plugin core/ldap/onChange
-```
+A write no request is behind, such as a scheduled task's, gets `{}`. The LDAP
+`ldap*done` hooks receive the same context after their arguments.
 
-All modifications trigger `onLdapChange`:
+The other hooks are derived from it:
 
-```bash
-PUT /api/v1/ldap/users/jdoe
-{
-  "replace": {
-    "cn": "John A. Doe",
-    "telephoneNumber": "+1234567890"
-  },
-  "delete": ["description"]
-}
-```
+| Hook                      | Fires when                                                 | Parameters                             |
+| ------------------------- | ---------------------------------------------------------- | -------------------------------------- |
+| `onLdapChange`            | any attribute changed                                      | `(dn, changes)`                        |
+| `onLdapMailChange`        | `--mail-attribute` changed                                 | `(dn, oldMail, newMail)`               |
+| `onLdapQuotaChange`       | `--quota-attribute` changed                                | `(dn, mail, oldQuota, newQuota)`       |
+| `onLdapAliasChange`       | `--alias-attribute` changed                                | `(dn, mail, oldAliases, newAliases)`   |
+| `onLdapForwardChange`     | `--forward-attribute` changed                              | `(dn, mail, oldForwards, newForwards)` |
+| `onLdapDriveQuotaChange`  | `--drive-quota-attribute` changed                          | `(dn, oldQuota, newQuota)`             |
+| `onLdapDisplayNameChange` | the name built from `cn`, or `givenName` and `sn`, changed | `(dn, oldName, newName)`               |
 
-Hook receives:
+`changes` maps each attribute that changed to `[oldValues, newValues]`, the
+full values on each side, `null` where the attribute is absent:
 
-```javascript
-{
-  "cn": ["John Doe", "John A. Doe"],
-  "telephoneNumber": [null, "+1234567890"],
-  "description": ["Old description", null]
-}
+```text
+member was [a, b], the request added c:
+{ member: [['a', 'b'], ['a', 'b', 'c']] }
 ```
 
-## Integration Examples
-
-### With Twake James Mail Server
-
-```bash
---plugin core/ldap/onChange \
---plugin twake/james \
---plugin core/ldap/flatGeneric \
---ldap-flat-schema ./schemas/twake/users.json \
---mail-attribute mail \
---quota-attribute mailQuota \
---james-webadmin-url http://james:8000
-```
+## Operational attributes
 
-The James plugin listens to `onLdapMailChange` and `onLdapQuotaChange` hooks and automatically updates the James mail server.
-
-### Custom Integration Plugin
-
-Create a custom plugin that reacts to changes:
+A search returns no operational attribute unless asked by name, so neither
+side holds `pwdAccountLockedTime` or its kind by default, and a write changing
+only such an attribute fires no hook. A plugin that follows some declares them:
 
 ```typescript
-import DmPlugin from '../abstract/plugin';
-import { Hooks } from '../hooks';
-
-export default class CustomSync extends DmPlugin {
-  name = 'customSync';
-
-  dependencies = {
-    onChange: 'core/ldap/onChange',
-  };
-
-  hooks: Hooks = {
-    onLdapMailChange: async (dn, oldMail, newMail) => {
-      this.logger.info(`Mail changed: ${oldMail} → ${newMail}`);
-
-      try {
-        await fetch('https://api.example.com/update-email', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ dn, oldMail, newMail }),
-        });
-      } catch (err) {
-        this.logger.error(`Failed to sync mail change: ${err}`);
-      }
-    },
-  };
-}
+followedOperationalAttributes = ['pwdAccountLockedTime'];
 ```
 
-## Change Detection
+The entry is then read with `*` and every attribute a loaded plugin declares.
 
-### Replace Operations
+## What counts as a change
 
-```javascript
-// Before: mail = "old@example.com"
-{
-  replace: {
-    mail: 'new@example.com';
-  }
-}
-// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", "old@example.com", "new@example.com")
-```
-
-### Add Operations
+Values are compared as sets: a single value and a one-element array are equal,
+and so are two orderings of the same values. A write that leaves every value
+as it was, such as a `replace` with the current value, fires no hook.
 
-```javascript
-// Before: mail = undefined
-{
-  add: {
-    mail: 'new@example.com';
-  }
-}
-// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", null, "new@example.com")
-```
+## Timing and errors
 
-### Delete Operations
-
-```javascript
-// Before: mail = "old@example.com"
-{ delete: ["mail"] }
-// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", "old@example.com", null)
-```
-
-## Performance Considerations
-
-### Hook Execution
-
-- Hooks run **synchronously** within the modify operation
-- Slow hooks delay the LDAP response
-- Consider async operations with fire-and-forget for non-critical updates
-
-### Optimization Tips
-
-1. **Keep hooks fast**: Defer heavy work to background jobs
-2. **Use error handling**: Don't let hook failures block LDAP operations
-3. **Batch updates**: If possible, batch multiple hook calls
-4. **Cache external state**: Avoid redundant external API calls
-
-## Error Handling
-
-Hooks can throw errors to abort the LDAP modification:
-
-```javascript
-hooks: {
-  onLdapMailChange: async (dn, oldMail, newMail) => {
-    // Validate mail domain
-    if (!newMail.endsWith('@company.com')) {
-      throw new Error('Mail must be @company.com domain');
-    }
-
-    // Update mail server
-    try {
-      await mailServer.renameAccount(oldMail, newMail);
-    } catch (err) {
-      throw new Error(`Mail server update failed: ${err.message}`);
-    }
-  };
-}
-```
-
-If the hook throws, the LDAP modification is rolled back (if supported by LDAP server).
-
-## Debugging
-
-Enable debug logging to see change detection:
-
-```bash
---log-level debug
-```
-
-Output:
-
-```
-[debug] Detected mail change for uid=jdoe,ou=users,dc=example,dc=com: old@domain.com → new@domain.com
-[debug] Triggering onLdapMailChange hook
-[info] onLdapMailChange: Mail account renamed successfully
-```
+Hooks run after the directory has accepted the write, and the API answers
+without waiting for them. A hook that throws is logged; the write stays.
 
 ## Limitations
 
-1. **Only monitors modify operations**: Does not detect changes from direct LDAP clients
-2. **Requires old value lookup**: Fetches entry before modification for comparison
-3. **Single-valued attributes**: Best suited for single-valued attributes like mail
-4. **Synchronous execution**: Hooks block the LDAP response
-
-## See Also
-
-- [Twake James Plugin](twakeJames.md) - Mail server integration using onChange
-- [ldapFlatGeneric.md](ldapFlatGeneric.md) - Generic LDAP entity management
-- [Hooks Documentation](../src/hooks.ts) - All available hooks
+- Only writes made through LDAP-Rest are seen; a direct LDAP client's are not.
+- Entries moved by the [trash](trash.md) plugin are not seen, nor the entries
+  under a renamed container, which move with it.
+- Each write reads the entry before and after it: one search on each side.