ldap-rest 0.7.0 → 0.8.1

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

@@ -0,0 +1,113 @@
+import TwakePlugin from '../../abstract/twakePlugin';
+import { type Role } from '../../abstract/plugin';
+import { Hooks } from '../../hooks';
+/**
+ * Plugin to sync LDAP resources and users with Twake Calendar
+ *
+ * Monitors a LDAP branch for resources (meeting rooms, equipment, etc.)
+ * and automatically creates/updates/deletes them in Twake Calendar via WebAdmin API.
+ *
+ * Also propagates user identity changes (email, first name, last name) to the
+ * Twake Calendar "registered users" via the WebAdmin API.
+ */
+export default class Calendar extends TwakePlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        onLdapChange: string;
+    };
+    private resourceBase;
+    private resourceObjectClass;
+    private resourceCreator;
+    private resourceDomain;
+    private firstnameAttr;
+    private lastnameAttr;
+    constructor(server: import('../../bin').DM);
+    hooks: Hooks;
+    /**
+     * Check if a LDAP entry is a calendar resource
+     */
+    private isResource;
+    /**
+     * Whether a DN is the configured resource branch or sits below it.
+     *
+     * Compared RDN by RDN ({@link isDnInBranch}), not as text: a substring test
+     * took `cn=Salle,ou=resourcesArchive,…` for a resource when the branch was
+     * given as `ou=resources`, and missed a DN written `cn=Salle, ou=resources,
+     * …` — the spaces a client puts after its commas are not part of the DN.
+     *
+     * No configured branch means no branch restriction, as before.
+     */
+    private isInResourceBranch;
+    /**
+     * URL of one resource in the WebAdmin API.
+     *
+     * The id is a raw RDN value, so it can carry anything a directory accepts:
+     * `cn=Salle A/B` interpolated as such builds `/resources/Salle A/B`, a path
+     * naming another resource or none. Percent-encoding keeps it one segment.
+     */
+    private resourceUrl;
+    /**
+     * Build resource data for Calendar API from LDAP attributes
+     */
+    private buildResourceData;
+    /**
+     * The name a resource is known by in Calendar: the value of the entry's own
+     * RDN, escapes removed.
+     *
+     * Taken from the first RDN, whatever its attribute type, so that an entity
+     * whose mainAttribute is neither `cn` nor `uid` gets an id of its own. The
+     * previous derivation looked for `cn=`/`uid=` anywhere in the DN, so
+     * `o=Room 12,cn=zone,ou=resources,…` answered `zone`, its parent's id — a
+     * modify on that entry then patched another resource. It also cut the value
+     * at the first comma, escaped or not, so `cn=Salle\, 2` answered `Salle\`,
+     * an id two rooms could share.
+     *
+     * A DN with `cn=` or `uid=` as its own first RDN and no escape in its value
+     * — the shape a deployment has — answers exactly what it answered before.
+     */
+    private getResourceId;
+    /**
+     * Find a Calendar registered user by email.
+     *
+     * `GET /registeredUsers?email=…` answers the one user, or 404. Calendar
+     * lower-cases the address before matching it (James's `Username` folds both
+     * parts), which is also how it stores every address, so a case difference
+     * between LDAP and Calendar does not matter. The one record this misses is
+     * a legacy one whose stored address kept upper case, written without going
+     * through `Username`; the full-list lookup used before did find it.
+     *
+     * Calendar releases before 1.0.0.1 ignore the `email` parameter and answer
+     * the full list; the user is then picked from it, case-insensitively.
+     *
+     * @param email Address Calendar holds for the user
+     * @param log Log context of the calling sync
+     * @returns The registered user, or null when it is not registered or the
+     *   lookup failed (both logged)
+     */
+    private findRegisteredUser;
+    /**
+     * Synchronize an LDAP user's identity (email, first and last name) to the
+     * Twake Calendar registered users via the WebAdmin API.
+     *
+     * Registered users are keyed by an internal id: the user is looked up with
+     * `GET /registeredUsers?email=…` (see findRegisteredUser), then
+     * `PATCH /registeredUsers?id={id}` with the LDAP values.
+     *
+     * @param event Hook name, used for logging
+     * @param dn LDAP DN of the user
+     * @param lookupEmail Email used to locate the existing registered user.
+     *   Defaults to the user's current mail; pass the OLD mail when the email
+     *   itself is changing (Calendar still holds the previous address).
+     */
+    syncRegisteredUser(event: string, dn: string, lookupEmail?: string): Promise<void>;
+    /**
+     * Delete user data from Twake Calendar WebAdmin API
+     * Calls POST /users/{mail}?action=deleteData
+     * @param mail - The user's email address
+     * @returns Task information or null on error
+     */
+    deleteUserData(mail: string): Promise<{
+        taskId: string;
+    } | null>;
+}

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

@@ -1,63 +1,14 @@
-import TwakePlugin from '../../abstract/twakePlugin';
-import { type Role } from '../../abstract/plugin';
-import { Hooks } from '../../hooks';
 /**
- * Plugin to sync LDAP resources and users with Twake Calendar
+ * @deprecated Use `core/twake/calendar` instead. This file is a
+ * backwards-compatibility shim for setups that still load the plugin under
+ * its historical name, which undersold it: besides resources, it propagates
+ * user identity changes (email, first and last name) to Twake Calendar. It
+ * will be removed in a future major release.
  *
- * Monitors a LDAP branch for resources (meeting rooms, equipment, etc.)
- * and automatically creates/updates/deletes them in Twake Calendar via WebAdmin API.
- *
- * Also propagates user identity changes (email, first name, last name) to the
- * Twake Calendar "registered users" via the WebAdmin API.
+ * The instance keeps registering as `calendarResources`, so code looking it
+ * up by that name keeps finding it.
  */
-export default class CalendarResources extends TwakePlugin {
+import Calendar from './calendar';
+export default class CalendarResources extends Calendar {
     name: string;
-    roles: Role[];
-    dependencies: {
-        onLdapChange: string;
-    };
-    private resourceBase;
-    private resourceObjectClass;
-    private resourceCreator;
-    private resourceDomain;
-    private firstnameAttr;
-    private lastnameAttr;
-    constructor(server: import('../../bin').DM);
-    hooks: Hooks;
-    /**
-     * Check if a LDAP entry is a calendar resource
-     */
-    private isResource;
-    /**
-     * Build resource data for Calendar API from LDAP attributes
-     */
-    private buildResourceData;
-    /**
-     * Extract resource ID from DN
-     */
-    private getResourceId;
-    /**
-     * Synchronize an LDAP user's identity (email, first and last name) to the
-     * Twake Calendar registered users via the WebAdmin API.
-     *
-     * Registered users are keyed by an internal id, and `GET /registeredUsers`
-     * exposes no filter, so we list all registered users, locate the entry by
-     * email, then `PATCH /registeredUsers?id={id}` with the LDAP values.
-     *
-     * @param event Hook name, used for logging
-     * @param dn LDAP DN of the user
-     * @param lookupEmail Email used to locate the existing registered user.
-     *   Defaults to the user's current mail; pass the OLD mail when the email
-     *   itself is changing (Calendar still holds the previous address).
-     */
-    syncRegisteredUser(event: string, dn: string, lookupEmail?: string): Promise<void>;
-    /**
-     * Delete user data from Twake Calendar WebAdmin API
-     * Calls POST /users/{mail}?action=deleteData
-     * @param mail - The user's email address
-     * @returns Task information or null on error
-     */
-    deleteUserData(mail: string): Promise<{
-        taskId: string;
-    } | null>;
 }

package/docs/README.md

@@ -11,6 +11,7 @@ Installation, configuration and plugin usage.
 - **[Getting Started](usage/README.md)** - Quick start guide
 - **[Configuration](usage/configuration.md)** - CLI options and environment variables
 - **[Upgrading](usage/upgrading.md)** - What to check before deploying a new version
+- **[Directory audit](usage/directory-audit.md)** - What a schema would refuse in an existing directory
 - **[Plugins](usage/plugins/README.md)** - Documentation for all available plugins
 
 ### [Plugin Development](plugin-development/README.md)

package/docs/client-development/api/openapi.md

@@ -220,7 +220,7 @@ private pluginTags: Map<string, string> = new Map([
   ['ldapFlatGeneric', 'Entities'],
   ['ldapBulkImport', 'Bulk Import'],
   ['james', 'Apache James Integration'],
-  ['calendarResources', 'Calendar Resources'],
+  ['calendar', 'Twake Calendar'],
   ['configApi', 'Configuration'],
   ['static', 'Static Files'],
 ]);

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

@@ -34,7 +34,7 @@ This guide covers LDAP-Rest's browser libraries for building LDAP management int
 
 ## Overview
 
-LDAP-Rest provides four ready-to-use browser libraries for building LDAP management interfaces:
+LDAP-Rest provides ready-to-use browser libraries for building LDAP management interfaces:
 
 - **LdapTreeViewer** - Interactive hierarchical tree view of LDAP organizations
 - **LdapUserEditor** - Complete user management interface with organization tree, user list, and edit form

package/docs/plugin-development/dependencies.md

@@ -190,15 +190,18 @@ dependencies = {
 - **Consumes Hooks**: (Hooks provided by `onLdapChange`)
 - **Notes**: Synchronizes LDAP users/groups with Apache James mail server
 
-#### `calendarResources` (twake/calendarResources)
+#### `calendar` (twake/calendar)
 
-- **Dependencies**: None
+- **Dependencies**:
+  - `onLdapChange: 'core/ldap/onChange'` ⚠️ **Required**
 - **Provides Hooks**:
   - `ldapcalendarResourceadddone` - After calendar resource added
   - `ldapcalendarResourcemodifydone` - After calendar resource modified
   - `ldapcalendarResourcedeletedone` - After calendar resource deleted
-- **Consumes Hooks**: None
-- **Notes**: Synchronizes calendar resources with Twake Calendar
+  - `onLdapChange` - Propagates user email / name changes
+- **Consumes Hooks**: (Hooks provided by `onLdapChange`)
+- **Notes**: Synchronizes calendar resources and registered users with Twake
+  Calendar. Formerly `calendarResources`, still loadable under that name
 
 #### `appAccountsConsistency` (twake/appAccountsConsistency)
 
@@ -361,7 +364,7 @@ ldapOrganizations (core/ldap/organization)
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                              │
 │  ┌────────────────────────────┐      ┌──────────────────────────┐          │
-│  │        james               │      │  calendarResources       │          │
+│  │        james               │      │  calendar                │          │
 │  │  (Apache James sync)       │      │  (Twake Calendar sync)   │          │
 │  │                            │      │                          │          │
 │  │  Requires:                 │      │                          │          │
@@ -466,7 +469,7 @@ graph TB
 
     %% Twake Integration
     james[james]
-    calendar[calendarResources]
+    calendar[calendar]
 
     %% Utility
     static[static]
@@ -521,7 +524,7 @@ graph TB
 ### 4. Integration Plugins
 
 13. `james` - After `onChange` and `groups`
-14. `calendarResources` - Calendar sync (optional)
+14. `calendar` - Twake Calendar sync (optional)
 
 ### 5. Utility Plugins (can load anytime)
 

package/docs/presentations/en.md

@@ -100,7 +100,7 @@ export default class MyPlugin extends DmPlugin {
 ## Integrations
 
 - **twake/james** - Apache James Synchronization (mail)
-- **twake/calendarResources** - Calendar Resources
+- **twake/calendar** - Twake Calendar resources and users
 
 <!-- end_slide -->
 

package/docs/presentations/fr.md

@@ -100,7 +100,7 @@ export default class MyPlugin extends DmPlugin {
 ## Intégrations
 
 - **twake/james** - Synchronisation Apache James (mail)
-- **twake/calendarResources** - Ressources calendrier
+- **twake/calendar** - Ressources et utilisateurs Twake Calendar
 
 <!-- end_slide -->
 

package/docs/usage/README.md

@@ -87,4 +87,5 @@ The system will:
 - **[Configuration](configuration.md)** - CLI options and environment variables
 - **[Plugins](plugins/README.md)** - Choose and configure plugins
 - **[Upgrading](upgrading.md)** - What to check before deploying a new version
+- **[Directory audit](directory-audit.md)** - What a schema would refuse in an existing directory
 - **[Troubleshooting](troubleshooting.md)** - Problem resolution

package/docs/usage/configuration.md

@@ -35,7 +35,7 @@ All LDAP-Rest configuration options.
     - [core/auth/trustedProxy](#coreauthtrustedproxy)
   - [Twake Integration Plugins](#twake-integration-plugins)
     - [core/twake/james](#coretwakejames)
-    - [core/twake/calendarResources](#coretwakecalendarresources)
+    - [core/twake/calendar](#coretwakecalendar)
     - [core/twake/applicativeAccounts](#coretwakeapplicativeaccounts)
     - [core/twake/appAccountsConsistency](#coretwakeappaccountsconsistency)
   - [Utility Plugins](#utility-plugins)
@@ -92,18 +92,34 @@ export DM_PLUGINS="core/auth/token,core/ldap/flatGeneric,core/ldap/groups"
 
 ## LDAP Connection
 
-| CLI                          | Plural           | Env                      | Default                            | Description                |
-| ---------------------------- | ---------------- | ------------------------ | ---------------------------------- | -------------------------- |
-| `--ldap-url`                 | `--ldap-urls`    | `DM_LDAP_URL`            | `ldap://localhost`                 | LDAP server URL(s)         |
-| `--ldap-dn`                  |                  | `DM_LDAP_DN`             | `cn=admin,dc=example,dc=com`       | Bind DN                    |
-| `--ldap-pwd`                 |                  | `DM_LDAP_PWD`            | `admin`                            | Password                   |
-| `--ldap-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches       |
-| `--ldap-user-main-attribute` |                  | `DM_LDAP_USER_ATTRIBUTE` | `uid`                              | User identifier attribute  |
-| `--ldap-cache-max`           |                  | `DM_LDAP_CACHE_MAX`      | `1000`                             | Max cache entries          |
-| `--ldap-cache-ttl`           |                  | `DM_LDAP_CACHE_TTL`      | `300`                              | Cache TTL (seconds)        |
-| `--ldap-pool-size`           |                  | `DM_LDAP_POOL_SIZE`      | `5`                                | Connection pool size       |
-| `--ldap-connection-ttl`      |                  | `DM_LDAP_CONNECTION_TTL` | `60`                               | Connection TTL (seconds)   |
-| `--user-class`               | `--user-classes` | `DM_USER_CLASSES`        | `top,twakeAccount,twakeWhitePages` | Default user objectClasses |
+| CLI                          | Plural           | Env                      | Default                            | Description                                 |
+| ---------------------------- | ---------------- | ------------------------ | ---------------------------------- | ------------------------------------------- |
+| `--ldap-url`                 | `--ldap-urls`    | `DM_LDAP_URL`            | `ldap://localhost`                 | LDAP server URL(s)                          |
+| `--ldap-dn`                  |                  | `DM_LDAP_DN`             | `cn=admin,dc=example,dc=com`       | Bind DN                                     |
+| `--ldap-pwd`                 |                  | `DM_LDAP_PWD`            | `admin`                            | Password                                    |
+| `--ldap-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches                        |
+| `--ldap-user-main-attribute` |                  | `DM_LDAP_USER_ATTRIBUTE` | `uid`                              | User identifier attribute                   |
+| `--ldap-cache-max`           |                  | `DM_LDAP_CACHE_MAX`      | `1000`                             | Max cache entries                           |
+| `--ldap-cache-ttl`           |                  | `DM_LDAP_CACHE_TTL`      | `0`                                | Search cache TTL (seconds), `0` disables it |
+| `--ldap-pool-size`           |                  | `DM_LDAP_POOL_SIZE`      | `5`                                | Connection pool size                        |
+| `--ldap-connection-ttl`      |                  | `DM_LDAP_CONNECTION_TTL` | `60`                               | Connection TTL (seconds)                    |
+| `--user-class`               | `--user-classes` | `DM_USER_CLASSES`        | `top,twakeAccount,twakeWhitePages` | Default user objectClasses                  |
+
+### The search cache
+
+`--ldap-cache-ttl` holds the answers of non-paginated, base-scope searches —
+single-entry lookups by DN — for that many seconds. It is **off by default**:
+until the branch storing a result was repaired, nothing was ever cached, so no
+deployment has run with it on, and a cache that silently serves stale entries
+is not something to switch on for everyone at once.
+
+Writes made through this service (add, modify, rename, move, delete) drop what
+they change, the moved subtree included. Writes made anywhere else do not:
+another replica of this service, an LSC synchronisation, a hand-run
+`ldapmodify`. Each process caches on its own, and only its own writes drop what
+it cached. Turn the cache on when this service is the only writer, or when
+serving an entry up to `--ldap-cache-ttl` seconds old is acceptable; leave it
+at `0` otherwise.
 
 ## Special Attributes
 
@@ -188,7 +204,7 @@ Monitors LDAP modifications and triggers hooks for attribute changes. No configu
 
 #### `core/ldap/departmentSync`
 
-Maintains consistency of department links when organizations are renamed/moved. No configuration options - uses [core/ldap/organizations](#coreldaporganizations) settings.
+Maintains consistency of department links when organizations are renamed/moved: it recomputes the path of the organization and of its sub-organizations (those already holding one), then updates the link and path of the entries linked to any of them. The attributes are those the loaded schemas declare through the `organizationPath` and `organizationLink` roles, then the configured `--ldap-organization-path-attribute` and `--ldap-organization-link-attribute`. No configuration options of its own - uses [core/ldap/organizations](#coreldaporganizations) settings.
 
 #### `core/ldap/raw`
 
@@ -308,7 +324,9 @@ Empty means the plugin guards every path. Scoping several instances to different
 | `--james-mailbox-type-attribute` |                                 | `DM_JAMES_MAILBOX_TYPE_ATTRIBUTE` | `twakeMailboxType`      | Mailbox type attribute      |
 | `--ldap-concurrency`             |                                 | `DM_LDAP_CONCURRENCY`             | `10`                    | LDAP operations concurrency |
 
-#### `core/twake/calendarResources`
+#### `core/twake/calendar`
+
+Formerly `core/twake/calendarResources`, still accepted as a deprecated alias.
 
 | CLI                               | Env                                | Default                 | Description                   |
 | --------------------------------- | ---------------------------------- | ----------------------- | ----------------------------- |
@@ -319,6 +337,8 @@ Empty means the plugin guards every path. Scoping several instances to different
 | `--calendar-resource-objectclass` | `DM_CALENDAR_RESOURCE_OBJECTCLASS` |                         | Resource objectClass          |
 | `--calendar-resource-creator`     | `DM_CALENDAR_RESOURCE_CREATOR`     |                         | Resource creator              |
 | `--calendar-resource-domain`      | `DM_CALENDAR_RESOURCE_DOMAIN`      |                         | Resource domain               |
+| `--calendar-firstname-attribute`  | `DM_CALENDAR_FIRSTNAME_ATTRIBUTE`  | `givenName`             | Registered user first name    |
+| `--calendar-lastname-attribute`   | `DM_CALENDAR_LASTNAME_ATTRIBUTE`   | `sn`                    | Registered user last name     |
 
 #### `core/twake/applicativeAccounts`
 

package/docs/usage/directory-audit.md

@@ -0,0 +1,105 @@
+# Auditing a directory before a migration
+
+Tightening a validation pattern changes what the server accepts **from now
+on**. It says nothing about the entries already stored: a directory whose
+addresses were never anchored, or whose organization names predate the rule
+that now governs them, loads fine and then refuses the first update of every
+offending entry — which is discovered one support ticket at a time.
+
+`npm run audit:directory` reads a branch as it is and reports what the schema
+would refuse, so the work is known before the switch rather than after it.
+
+## Running it
+
+```sh
+export DM_LDAP_URL=ldap://directory.example.org
+export DM_LDAP_DN='cn=admin,dc=example,dc=com'
+export DM_LDAP_PWD='…'
+export DM_LDAP_BASE='dc=example,dc=com'
+
+npm run audit:directory -- --schema static/schemas/twake/users.json \
+  --plugin core/ldap/enterpriseRules
+```
+
+| Option            | Default                      | Purpose                             |
+| ----------------- | ---------------------------- | ----------------------------------- |
+| `--schema`        | _(required)_                 | Schema to check against             |
+| `--base`          | the schema's own entity base | Branch to read                      |
+| `--filter`        | `(objectClass=*)`            | Narrows what is audited             |
+| `--url`           | `DM_LDAP_URL`                | Directory to read                   |
+| `--bind-dn`       | `DM_LDAP_DN`                 | Identity to read with               |
+| `--bind-password` | `DM_LDAP_PWD`                | Its password                        |
+| `--samples`       | `5`                          | Offending entries named per finding |
+| `--plugin`        | _(none)_                     | A plugin the server loads, repeated |
+
+`--plugin` matters for the attributes a schema marks both `required` and
+`generated`. The server exempts one from its check only when something fills
+it: the entity itself (`generatedFrom`), or a loaded plugin. Name the plugins
+the server loads and the audit exempts what they fill; without them it reports
+those attributes as `missing, and no --plugin fills it` — which is what every
+creation would be refused for on a server that does not load them.
+
+It exits `0` when the branch is clean, `1` when the schema would refuse
+something, and `2` when the audit itself could not run — an unreadable schema,
+a directory that would not answer — so a pipeline can tell "dirty" from
+"broken" rather than gating on both alike.
+
+`--bind-password` puts the password in `ps` and in the shell history of
+whoever runs it. `DM_LDAP_PWD` is the path to prefer, and the flag is there
+for parity with the server's own `--ldap-pwd`.
+
+## What it checks, and what only the server can
+
+The audit reads a schema and an entry, so it answers what an entry alone can
+answer: required attributes, the `test` pattern of a value and of an array's
+elements, and the branch a DN must land in. It replaces `__KEY__` placeholders
+and `{config_key}` in `entity.base` from the `DM_*` environment exactly as the
+server does, leaving a placeholder the configuration does not name.
+
+What it does not answer needs the rest of the directory, and belongs to a dry
+run rather than here: uniqueness across a namespace, the mail domains an
+organization owns, and anything a plugin computes after validation. A clean
+audit is not a promise that every entry will survive every rule — it is a
+promise that none of them fails on its own contents.
+
+## Reading the report
+
+```
+12632 entries read, 47 value(s) the schema would refuse:
+
+  mail: does not match — 41
+    expected: Expected an address in the example.org domain, at most 64 characters before the @
+    uid=jean.dupont,ou=users,dc=example,dc=com → "jean.dupont@old-domain.example"
+    …and 36 more
+
+  postalCode: does not match — 6
+    expected: Expected pattern 9999, A9999 or R9999
+    uid=marie.martin,ou=users,dc=example,dc=com → "1234"
+```
+
+Each finding names the attribute, why it was refused, and — from the schema's
+`hint` — what a valid value looks like. The same wording reaches the person
+filling the form, so the fix and the rule are described identically.
+
+## What it checks, and what it cannot
+
+Checked, because an entry answers for itself:
+
+- `test` patterns, on single and multi-valued attributes
+- `required` attributes that are absent — except the ones the server computes
+  (`generated`), which an entry is not expected to carry yet
+- the `branch` a `pointer` must land in
+
+Not checked, because it takes the whole directory or a live server:
+
+- uniqueness across a shared namespace
+- mail addresses against the domains an organization owns
+- anything a hook computes rather than validates
+
+For those, run the target configuration against a copy of the directory and
+replay the writes.
+
+## See also
+
+- [flat-generic](plugins/ldap/flat-generic.md) — where `test` and `hint` live
+- [enterprise-rules](plugins/ldap/enterprise-rules.md) — the rules a dry run covers

package/docs/usage/plugins/README.md

@@ -52,12 +52,12 @@ Protection and rate limiting:
 
 Connect to external systems:
 
-| Plugin                                                   | Description                  |
-| -------------------------------------------------------- | ---------------------------- |
-| [james-mail](integrations/james-mail.md)                 | Apache James synchronization |
-| [james-mailboxes](integrations/james-mailboxes.md)       | Apache James team mailboxes  |
-| [calendar-resources](integrations/calendar-resources.md) | Twake calendar resources     |
-| [app-accounts](integrations/app-accounts.md)             | Applicative accounts API     |
+| Plugin                                             | Description                        |
+| -------------------------------------------------- | ---------------------------------- |
+| [james-mail](integrations/james-mail.md)           | Apache James synchronization       |
+| [james-mailboxes](integrations/james-mailboxes.md) | Apache James team mailboxes        |
+| [calendar](integrations/calendar.md)               | Twake Calendar resources and users |
+| [app-accounts](integrations/app-accounts.md)       | Applicative accounts API           |
 
 ## Utility Plugins
 

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

@@ -14,11 +14,12 @@ LDAP-Rest provides multiple authentication plugins to secure API access. These p
 
 ## Authorization Plugins
 
-| Method                                          | Plugin                     | Description                 |
-| ----------------------------------------------- | -------------------------- | --------------------------- |
-| [Authorization Per Branch](authz-per-branch.md) | `core/auth/authzPerBranch` | Branch-level access control |
-| [Authorization Per Route](authz-per-route.md)   | `core/auth/authzPerRoute`  | HTTP route-level ACL        |
-| [Authorization LinID 1.x](authz-linid1.md)      | `core/auth/authzLinid1`    | LinID 1.x integration       |
+| Method                                          | Plugin                     | Description                  |
+| ----------------------------------------------- | -------------------------- | ---------------------------- |
+| [Authorization Per Branch](authz-per-branch.md) | `core/auth/authzPerBranch` | Branch-level access control  |
+| [Authorization Per Route](authz-per-route.md)   | `core/auth/authzPerRoute`  | HTTP route-level ACL         |
+| [Authorization LinID 1.x](authz-linid1.md)      | `core/auth/authzLinid1`    | LinID 1.x integration        |
+| [Authorization Scope](authz-scope.md)           | `core/auth/authzScope`     | What the current user may do |
 
 ## Security Plugins
 

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

@@ -0,0 +1,103 @@
+# Authorization Scope Plugin
+
+Tells a client what the signed-in administrator may actually do, before it
+offers them a button that will fail.
+
+In a local-administration model the scope _is_ the interface: a manager
+administers a few branches of the tree and nothing else, and an application
+that cannot name those branches leaves them guessing. This endpoint answers
+both halves — which branches, and which entities can be created — by asking
+whichever authorization plugin is in force.
+
+## Configuration
+
+```bash
+--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
+[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.
+
+## Endpoint
+
+```
+GET /api/v1/authz/scope
+```
+
+```json
+{
+  "user": "uid=alice,ou=users,dc=example,dc=com",
+  "unrestricted": false,
+  "branches": [
+    {
+      "dn": "ou=Sales,ou=organization,dc=example,dc=com",
+      "name": "Sales",
+      "path": "Acme / Sales",
+      "read": true,
+      "write": true,
+      "delete": true
+    }
+  ],
+  "entities": [
+    { "name": "users", "base": "ou=users,dc=example,dc=com", "create": true },
+    { "name": "groups", "base": "ou=groups,dc=example,dc=com", "create": true },
+    {
+      "name": "organizations",
+      "base": "ou=organization,dc=example,dc=com",
+      "create": false
+    }
+  ]
+}
+```
+
+`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.
+
+`create` answers "may I add one of these?", on the rule the add hook enforces.
+An entry that can carry the organization link (its schema declares the
+configured link attribute) is scoped by the organization it is attached to, so
+the answer is yes as soon as the caller may write in a branch they administer.
+One that cannot — a position, a nomenclature row — is checked against the
+branch it lands in, so the answer is whether the caller may write there.
+Organizations are the other exception, since they live in the tree itself and
+need write permission on the node they hang from — the top of the tree, which
+is where a new organization goes when the client names no parent. A local administrator of one branch therefore reads
+`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:
+
+```json
+{
+  "user": "alice",
+  "unrestricted": true,
+  "branches": [],
+  "entities": [
+    { "name": "users", "base": "ou=users,dc=example,dc=com", "create": true }
+  ]
+}
+```
+
+## Errors
+
+| Status | When                                                          |
+| ------ | ------------------------------------------------------------- |
+| `401`  | No authenticated user, or a user the directory cannot resolve |
+
+## See also
+
+- [authz-linid1](authz-linid1.md) — the local-administrator model this serves
+- [authz-per-branch](authz-per-branch.md) — static per-branch permissions

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

@@ -21,6 +21,23 @@ DM_LLNG_INI="/etc/lemonldap-ng/lemonldap-ng.ini"
 2. **LLNG Configuration**: Valid `lemonldap-ng.ini` file
 3. **Virtual Host Configuration**: LDAP-Rest must be configured as a protected application in LLNG
 
+The handler runs inside LDAP-Rest and reads `lemonldap-ng.ini` when the server
+starts. The file tells it where the LLNG configuration is, and which virtual
+hosts it protects — a Node.js handler serves only those listed in
+`nodeVhosts`:
+
+```ini
+[configuration]
+type = REST
+baseConfigUrl = https://auth.example.com/index.fcgi/config
+
+[node-handler]
+nodeVhosts = api.example.com
+```
+
+A file that cannot be read, a configuration that cannot be reached or a
+missing `nodeVhosts` stops the server at startup, with the reason.
+
 ## How It Works
 
 1. Uses the LemonLDAP::NG Handler to validate requests