ldap-rest 0.7.0 → 0.8.0

package/dist/src/config/schema.d.ts

@@ -1,18 +1,388 @@
 import type { AttributeValue } from '../lib/ldapActions';
+/**
+ * Scalar and container types an entity schema may declare.
+ *
+ * `pointer` is a DN reference validated against `branch`; `date` is an LDAP
+ * generalized time (`yyyyMMddHHmmss[.SSS]Z`).
+ */
+export type SchemaAttributeType = 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'array' | 'pointer';
+/**
+ * Semantic role of an attribute: what it *means*, independent of the concrete
+ * LDAP attribute holding it. Core code is written against roles so that a
+ * deployment with a different directory layout reuses it unchanged — the name
+ * of the attribute and the values it takes are configuration.
+ *
+ * The type is a plain string: the list below is what the core itself looks
+ * for, and a deployment is free to add its own for its plugins.
+ *
+ * | Role               | Meaning                                              |
+ * | ------------------ | ---------------------------------------------------- |
+ * | `identifier`       | RDN value of the entry                               |
+ * | `displayName`      | Human-readable name                                  |
+ * | `primaryEmail`     | Main mail address                                    |
+ * | `emailAliases`     | Further addresses of the same mailbox                |
+ * | `emailQuota`       | Mailbox size limit, in bytes                         |
+ * | `organizationLink` | DN of the organization the entry belongs to          |
+ * | `organizationPath` | Human-readable path of that organization             |
+ * | `members`          | DNs of the members of a group                        |
+ * | `owners`           | DNs allowed to write to a restricted group           |
+ * | `accountStatus`    | Lifecycle state of an account (enabled / disabled…)  |
+ * | `password`         | Credential                                           |
+ * | `passwordReset`    | Flag forcing a password change at next login         |
+ * | `accountExpiry`    | Date after which the account is to be removed        |
+ * | `domainLink`       | DNs of the mail domains an organization may use      |
+ * | `domainName`       | Domain name carried by a domain entry                |
+ */
+export type SchemaRole = string;
+/**
+ * A piece of text a client shows, in one or several languages.
+ *
+ * A plain string is the text itself. A map is keyed by language tag, and a
+ * client picks the closest one it can:
+ *
+ * ```json
+ * "label": { "en": "Department", "fr": "Département" }
+ * ```
+ *
+ * These words belong to the deployment, not to the product — they name *its*
+ * entities and attributes — so their translations belong in its schemas
+ * rather than in a catalogue shipped with the code.
+ */
+export type LocalizedText = string | Record<string, string>;
+/** Roles the core itself looks for. See {@link SchemaRole}. */
+export declare const CORE_ROLES: readonly ["identifier", "displayName", "primaryEmail", "emailAliases", "emailQuota", "organizationLink", "organizationPath", "members", "owners", "accountStatus", "password", "passwordReset", "accountExpiry", "domainLink", "domainName"];
+/**
+ * How a uniqueness constraint is evaluated.
+ *
+ * By default the value must be unique among the entries of the entity's own
+ * branch. `branches` widens the search to a shared namespace — a mail address
+ * belongs to accounts *and* to distribution lists — and `attributes` names the
+ * other attributes that hold values of that same namespace.
+ */
+export interface UniqueConstraint {
+    /**
+     * Extra branches searched besides the entity's own base. Each entry may use
+     * the `__ldap_base__` placeholder, like `branch`.
+     */
+    branches?: string[];
+    /**
+     * Other attributes sharing the value namespace, searched alongside the
+     * attribute itself (e.g. `mailAlternateAddress` for `mail`).
+     */
+    attributes?: string[];
+    /**
+     * Value exempted from the check. A directory may use a placeholder for
+     * non-individual entries (a shared payroll number, say); that value is
+     * allowed to repeat.
+     */
+    sentinel?: string;
+    /** Extra LDAP filter narrowing the search, e.g. `(objectClass=twakeAccount)` */
+    filter?: string;
+}
+/**
+ * Derivation of a generated attribute from another attribute of the same
+ * entry. Used for identifiers built from the mail address, where the client
+ * never supplies the value.
+ */
+export interface GeneratedFrom {
+    /** Source attribute, e.g. `mail` */
+    attribute: string;
+    /**
+     * Regex whose first capturing group is the generated value. Applied to the
+     * source value; when it does not match, the whole source value is used.
+     */
+    extract?: string;
+    /** Lowercase the result */
+    lowercase?: boolean;
+    /**
+     * Characters to drop from the extracted value, as an extended regular
+     * expression. A mail local part may legally hold `+`, `'` or `!`, which an
+     * identifier charset usually refuses; without this the entry becomes
+     * uncreatable, since the client may not send the generated attribute
+     * either. `[^a-zA-Z0-9._-]` keeps what a `uid` accepts.
+     */
+    strip?: string;
+    /**
+     * What to do when the generated value is already taken. `error` (the
+     * default) refuses the creation; `suffix` appends `-2`, `-3`, … until a free
+     * value is found.
+     */
+    onCollision?: 'error' | 'suffix';
+}
+export interface SchemaAttribute {
+    type: SchemaAttributeType;
+    items?: {
+        type: string;
+        test?: string | RegExp;
+        hint?: string;
+        branch?: string[];
+    };
+    default?: AttributeValue;
+    required?: boolean;
+    test?: string | RegExp;
+    /**
+     * Plain-language description of `test`, shown to the user *before* they get
+     * a value wrong — "Expected pattern 999 9999". It travels with the
+     * schema so the pattern and its explanation cannot drift apart, and so a
+     * client never has to hardcode either.
+     */
+    hint?: string;
+    branch?: string[];
+    fixed?: boolean;
+    /** Semantic role(s) — see {@link SchemaRole} */
+    role?: SchemaRole | SchemaRole[];
+    /**
+     * Computed server-side. Refused when a client supplies it; still writable by
+     * the core and by plugins.
+     *
+     * The refusal is about *attribute names in a payload*, not about the entry
+     * being immutable: an endpoint parameter that happens to end up in a
+     * generated attribute is not one of them. `POST /ldap/{resource}/{id}/rename`
+     * takes a `newId` and `POST /ldap/{resource}/{id}/move` a `targetOrgDn`, and
+     * both then write a `generated` attribute themselves — while
+     * `PUT /ldap/{resource}/{id}` naming that attribute is still refused.
+     */
+    generated?: boolean;
+    /** How a `generated` value is derived from another attribute */
+    generatedFrom?: GeneratedFrom;
+    /**
+     * Operational or derived attribute: refused in input and never written.
+     * `memberOf` is the archetype — membership is driven from the group side.
+     */
+    readOnly?: boolean;
+    /**
+     * Never returned to a client, though it may still be written. Covers the
+     * write-only attributes of a password reset.
+     */
+    neverReturn?: boolean;
+    /** Value must be unique; `true` means "unique within this entity" */
+    unique?: boolean | UniqueConstraint;
+    /**
+     * Canonicalisation applied to an incoming value before it is stored.
+     *
+     * `byteSize` reads a human-readable size (`5GB`, `500MB`, `2048`) and stores
+     * the number of bytes, so the same value means the same thing whether it
+     * arrived on a creation or an update.
+     */
+    normalize?: 'byteSize';
+    /**
+     * Whether a client's "search everywhere" should include this attribute.
+     *
+     * Which attributes can be searched at all is a property of the deployment,
+     * not of the code: a substring filter on an attribute the directory has not
+     * indexed scans the branch. A schema that marks none leaves the client to
+     * guess — every returnable, single-valued, non-pointer attribute — which is
+     * right for a small branch and wrong for a large one. Marking even one
+     * attribute replaces the guess entirely, so the list is exactly what the
+     * deployment indexed.
+     */
+    searchable?: boolean;
+    /**
+     * Named states of a lifecycle attribute, mapping a semantic name the API
+     * speaks (`enabled`, `disabled`) to the concrete value this directory
+     * stores. What "disabled" *is* — a DN in a nomenclature, a string, a
+     * boolean — is a property of the deployment, never of the code.
+     */
+    states?: Record<string, AttributeValue>;
+    /**
+     * For a `pointer`: refuse to delete the entry it points at while any entry
+     * still references it. `ignore` (the default) leaves the reference dangling.
+     */
+    referentialIntegrity?: 'restrict' | 'ignore';
+    /**
+     * For a `members`-role attribute: refuse to delete the entry while it still
+     * has members. The placeholder member some directories need to keep a
+     * `groupOfNames` valid (`--group-dummy-user`) does not count.
+     */
+    deleteGuard?: 'nonEmpty';
+    /**
+     * For a mail attribute: which set of domains the address must belong to.
+     *
+     * `organization` walks up from the entry's organization, collecting the
+     * domains declared on it and on each of its ancestors; `directory` accepts
+     * any domain declared anywhere in the directory. When no domain is declared
+     * at all, any address passes.
+     */
+    mailDomainScope?: 'organization' | 'directory';
+    /**
+     * Accept a subdomain of an authorised domain — `list@lists.example.org`
+     * under `example.org`. Off by default: the domain must match exactly.
+     */
+    allowSubdomains?: boolean;
+    /** Grouping hint for a form, e.g. `Mailbox Settings` */
+    group?: string;
+    /** Name a client shows for this attribute, in one or several languages */
+    label?: LocalizedText;
+}
 export interface Schema {
     strict: boolean;
     attributes: {
-        [key: string]: {
-            type: 'string' | 'array' | 'pointer';
-            items?: {
-                type: string;
-                test?: string | RegExp;
-            };
-            default?: AttributeValue;
-            required?: boolean;
-            test?: string | RegExp;
-            branch?: string[];
-            fixed?: boolean;
-        };
+        [key: string]: SchemaAttribute;
+    };
+    /**
+     * Metadata about the entity itself, present in a schema file loaded by
+     * `ldapFlatGeneric` (the whole file is parsed as a `Schema`, so this is what
+     * that parse actually carries — narrowing to the declared type must not
+     * silently drop it). A schema attached to a plugin without its own file
+     * carries none of this.
+     */
+    entity?: {
+        /** Name a client shows for the collection, in one or several languages */
+        label?: LocalizedText;
+        /** Same, for a single entry */
+        singularLabel?: LocalizedText;
+        /**
+         * What a client shows for an entry, keyed by its main attribute value:
+         * the readable name of a nomenclature value a pointer lands on
+         */
+        valueLabels?: Record<string, LocalizedText>;
     };
 }
+/**
+ * Tell whether an attribute carries a given semantic role.
+ *
+ * @param attr attribute definition
+ * @param role role to look for
+ * @returns true when the attribute declares that role
+ */
+export declare function hasRole(attr: SchemaAttribute | undefined, role: SchemaRole): boolean;
+/**
+ * Find the attribute of a schema carrying a given semantic role.
+ *
+ * This is the lookup that keeps core code free of concrete attribute names:
+ * `roleAttribute(schema, 'accountStatus')` returns `twakeAccountStatus` for a
+ * Twake directory and whatever another deployment chose for its own.
+ *
+ * @param schema entity schema
+ * @param role role to look for
+ * @returns attribute name, or undefined when no attribute declares that role
+ */
+export declare function roleAttribute(schema: Schema | undefined, role: SchemaRole): string | undefined;
+/**
+ * Find every attribute of a schema carrying a given semantic role.
+ *
+ * @param schema entity schema
+ * @param role role to look for
+ * @returns attribute names, in declaration order
+ */
+export declare function roleAttributes(schema: Schema | undefined, role: SchemaRole): string[];
+/**
+ * Find an attribute definition by the name a request or the directory uses.
+ *
+ * LDAP attribute names are case-insensitive and may carry options
+ * (`cn;lang-fr`), while schema keys are written in one spelling. Looking a
+ * name up verbatim lets `TWAKEDEPARTMENTPATH` slip past a rule written for
+ * `twakeDepartmentPath`, though the directory treats both as the same.
+ *
+ * @param schema entity schema
+ * @param name attribute name, in any case, with or without options
+ * @returns the schema's own spelling and the definition, or undefined
+ */
+export declare function schemaAttribute(schema: Schema | undefined, name: string): [string, SchemaAttribute] | undefined;
+/**
+ * Every attribute name a modify request touches: added, replaced or deleted.
+ *
+ * A delete counts as much as a replace: removing a computed attribute is
+ * setting it, to nothing, and nothing the client does afterwards can put it
+ * back. `delete` comes as a list of names or as an object of values to remove.
+ *
+ * @param body modify request
+ * @returns attribute names, as the client spelt them
+ */
+export declare function modifiedAttributeNames(body: {
+    add?: object;
+    replace?: object;
+    delete?: string[] | object;
+}): string[];
+/**
+ * Lowercased names of the attributes marked `neverReturn` in any of the given
+ * schemas.
+ *
+ * @param schemas schemas to read, undefined entries skipped
+ * @returns lowercased attribute names
+ */
+export declare function neverReturnAttributes(schemas: Iterable<Schema | undefined>): Set<string>;
+/**
+ * Copy an entry without the attributes of a hidden set.
+ *
+ * @param entry entry about to be serialised
+ * @param hidden lowercased attribute names to leave out
+ * @returns the entry itself when nothing is hidden, a filtered copy otherwise
+ */
+export declare function withoutAttributes<T extends object>(entry: T, hidden: Set<string>): T;
+/**
+ * Check the DNs an attribute carries: a `pointer`, or an array whose `items`
+ * are pointers or declare a `branch`.
+ *
+ * Each DN has to sit inside one of the declared branches, compared RDN by RDN
+ * (a suffix match reads `uid=x,xou=users,…` as inside `ou=users,…`), and a
+ * pointer has to name an entry that exists. The flat entities checked the
+ * branch of a single pointer; organizations and groups read neither `items`
+ * rule, so an organization accepted a domain link to a DN outside the domains
+ * branch, or to none at all — and lost its mail-domain restriction with it.
+ *
+ * @param field attribute name, for the messages
+ * @param attr its schema definition
+ * @param value value submitted
+ * @param entryExists tells whether a DN names an existing entry
+ * @throws BadRequestError naming the first DN that breaks a rule
+ */
+export declare function checkDnValues(field: string, attr: SchemaAttribute, value: AttributeValue, entryExists: (dn: string) => Promise<boolean>): Promise<void>;
+/**
+ * Tell whether every value of an attribute matches its pattern: `test`, or
+ * `items.test` for the elements of an array.
+ *
+ * @param attr schema definition
+ * @param value value submitted
+ * @returns false when one value does not match
+ */
+export declare function matchesPattern(attr: SchemaAttribute, value: AttributeValue): boolean;
+/**
+ * Refuse a payload naming an attribute the server owns.
+ *
+ * `generated` and `readOnly` say a value is not the client's to set. The flat
+ * entities enforce it on their own paths; organizations and groups have their
+ * own routes and need the same guard, or an endpoint promising that a computed
+ * path "cannot be changed here" quietly accepts one.
+ *
+ * @param schema entity schema, when one is loaded
+ * @param names attribute names carried by the request
+ * @param mainAttribute RDN attribute, exempt when nothing derives it
+ * @throws BadRequestError naming the first attribute the client may not set
+ */
+export declare function assertClientMaySet(schema: Schema | undefined, names: string[], mainAttribute?: string): void;
+/**
+ * A plugin able to say whether it fills a given generated attribute.
+ *
+ * Declaring the method is the whole contract: an entity asks before it
+ * exempts a required attribute from its check, so the answer has to be about
+ * that attribute, not about a role the plugin happens to carry.
+ */
+export interface GeneratedAttributeFiller {
+    fillsGeneratedAttribute?: (name: string, attr: SchemaAttribute, schema: Schema) => boolean;
+}
+/**
+ * Name the first required attribute a new entry fails to provide.
+ *
+ * A `generated` attribute is exempt: it is filled by a hook *after*
+ * validation, on purpose — checks must see the payload as the client sent it,
+ * never a value the server has already rewritten.
+ *
+ * Exempt only when something will actually fill it. `generatedFrom` is
+ * derived by the entity itself; for the rest, ask the loaded plugins about
+ * *this* attribute rather than trusting a role a dozen of them carry. With no
+ * filler — a server upgraded without adding `core/ldap/enterpriseRules` —
+ * exempting would write an entry missing an attribute its own schema calls
+ * required, silently, and the client could not supply it either since
+ * `generated` is refused as input. The entry would be unwritable by any
+ * route, so demand it and say so instead.
+ *
+ * Every entity runs this check: the flat branches, the organizations and the
+ * groups, each wording the refusal in its own terms.
+ *
+ * @param schema entity schema, when one is loaded
+ * @param entry entry as the client sent it
+ * @param plugins loaded plugins, asked about each generated attribute
+ * @returns the attribute name to complain about, or undefined
+ */
+export declare function missingRequiredAttribute(schema: Schema | undefined, entry: Record<string, unknown>, plugins: Record<string, unknown>): string | undefined;

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

@@ -11,6 +11,20 @@ export declare const tryMethodData: (res: Response, method: Function, ...args: u
 export declare const ok: (res: Response, data?: object) => void;
 export declare const created: (res: Response, data?: object) => void;
 export declare const noContent: (res: Response) => void;
+/**
+ * A request whose parts did not all succeed, and whose failure cannot be
+ * undone (RFC 4918 section 13).
+ *
+ * An entry rename rewrites the references other entries hold to it. The
+ * rename itself is the only rollback point: once the directory has accepted
+ * it, a reference that could not be rewritten leaves the directory partly
+ * inconsistent, and answering 200 would hide it while answering 500 would
+ * claim nothing happened. The body says what was done and what was not.
+ *
+ * @param res express response
+ * @param data report of what succeeded and what did not
+ */
+export declare const multiStatus: (res: Response, data: object) => void;
 export declare const badRequest: (res: Response, message?: string) => void;
 export declare const unauthorized: (res: Response, message?: string) => void;
 export declare const forbidden: (res: Response, message?: string) => void;

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

@@ -1,7 +1,3 @@
-/**
- * LDAP low-level library
- * @author Xavier Guimard <xguimard@linagora.com>
- */
 import type { Request } from 'express';
 import type { ClientOptions, SearchResult, SearchOptions } from 'ldapts';
 import type winston from 'winston';
@@ -47,6 +43,22 @@ declare class ldapActions {
     parent: DM;
     logger: winston.Logger;
     private searchCache;
+    private cacheEnabled;
+    /**
+     * How many writes this instance has made since it was built.
+     *
+     * A read can be overtaken by a write: the write lands and `invalidateCache`
+     * finds nothing to drop, because the read has not stored its answer yet —
+     * and the read then stores what it read *before* the write, an entry
+     * nothing will drop until its TTL runs out. `search()` remembers the count
+     * it started at and stores only if no write happened in between, so a read
+     * a write overtook costs a cache entry, never a stale answer.
+     *
+     * The count is per instance and per write, not per DN: a write to another
+     * branch keeps a concurrent read out of the cache too. That is hit rate
+     * given up, not freshness.
+     */
+    private cacheGeneration;
     queryLimit: ReturnType<typeof pLimit>;
     private connectionPool;
     private poolSize;
@@ -83,11 +95,26 @@ declare class ldapActions {
     private getAttributeSignature;
     /**
      * Generate cache key for LDAP search
+     *
+     * Every option that changes the answer belongs in here, or a search that
+     * asked for more is served what a search that asked for less got: the
+     * requested attributes above all, but also the ones that change the shape
+     * of what comes back. `timeLimit` is deliberately absent — it bounds how
+     * long the server may spend, not what it returns.
      */
     private getCacheKey;
     /**
-     * Invalidate cache entries for a specific DN
-     * Called after modifications to ensure cache consistency
+     * Drop every cached read of `dn`, and of everything below it.
+     *
+     * Called after each write, so the next read of what just changed goes to
+     * the directory. Two things this does that a `key.startsWith(dn)` test did
+     * not: it compares DNs the way the directory does (see {@link foldDn}), so
+     * a write spelling a DN differently from the read that cached it still
+     * drops it; and it drops the subtree, because `rename()` and `move()`
+     * re-parent a whole branch in one operation — renaming an organization
+     * changes the DN of every entry under it — leaving the cached reads of
+     * those children filed under DNs that no longer exist. A leaf has nothing
+     * below it and the extra test costs nothing.
      */
     invalidateCache(dn: string): void;
     /**

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

@@ -41,6 +41,30 @@ export declare const transformSchemas: (schemas: string | Buffer, config: Config
  * ```
  */
 export declare function escapeLdapFilter(value: string): string;
+/**
+ * Build the LDAP filter of a list search: a substring match on one attribute,
+ * or on any of several.
+ *
+ * The value is escaped, so nothing a client types can reach the filter as
+ * syntax; the attribute names cannot be escaped — they *are* syntax — so they
+ * are checked against what an LDAP attribute name may contain and refused
+ * otherwise.
+ *
+ * Every list route builds the same filter, and a client asking for a mail
+ * address expects the same answer whichever entity it is asking about.
+ *
+ * @param match - The substring to look for
+ * @param attribute - One attribute name, or several separated by commas
+ * @returns The LDAP filter
+ * @throws BadRequestError when an attribute name is not one
+ *
+ * @example
+ * ```typescript
+ * substringSearchFilter('ali', 'cn,mail')
+ * // => '(|(cn=*ali*)(mail=*ali*))'
+ * ```
+ */
+export declare function substringSearchFilter(match: string, attribute: string): string;
 /**
  * Escape special characters in LDAP DN attribute values according to RFC 4514
  * Prevents LDAP injection attacks by escaping characters that have special meaning in DNs
@@ -145,6 +169,22 @@ export declare function getParentDn(dn: string): string;
  * ```
  */
 export declare function getRdn(dn: string): string;
+/**
+ * Extract the *value* of the first RDN of a DN, with its escapes removed
+ *
+ * Where {@link getRdn} returns `ou=Test Org`, this returns `Test Org`: the
+ * name the entry is known by, which is what a path or a label is built from.
+ *
+ * @param dn - The DN to read
+ * @returns The value, or an empty string when the DN has no RDN
+ *
+ * @example
+ * ```typescript
+ * rdnValue('ou=Test\\, Org,ou=organization,dc=example,dc=com')
+ * // => 'Test, Org'
+ * ```
+ */
+export declare function rdnValue(dn: string): string;
 /**
  * Check if a DN is a child of another DN
  *
@@ -184,6 +224,31 @@ export declare function isChildOf(dn: string, parentDn: string): boolean;
  * ```
  */
 export declare function normalizeDn(dn: string): string;
+/**
+ * Whether a member DN is the placeholder a `groupOfNames` holds so it stays
+ * valid with no real member (`--group-dummy-user`).
+ *
+ * Compared as DNs rather than as text: the directory answers with its own
+ * spelling, so the configured `uid=fakeUser,ou=users,…` has to match the
+ * `uid=fakeuser, ou=users,…` a group may actually hold. A textual comparison
+ * counted such a member as a real one — enough to make an empty group refuse
+ * deletion, and to show the placeholder to SCIM clients.
+ *
+ * Every reader of the member list asks here, so the four of them cannot drift
+ * apart again.
+ *
+ * @param member - The member DN to test
+ * @param dummy - The configured placeholder DN, if any
+ * @returns true when `member` is that placeholder; false when none is
+ *          configured, as there is then no placeholder to hide
+ *
+ * @example
+ * ```typescript
+ * isDummyMemberDn('uid=fakeuser, ou=users,dc=e,dc=c', 'uid=fakeUser,ou=users,dc=e,dc=c')
+ * // => true
+ * ```
+ */
+export declare function isDummyMemberDn(member: unknown, dummy: string | undefined): boolean;
 /**
  * Check whether a DN is a branch base itself or sits anywhere below it.
  *

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

@@ -0,0 +1,53 @@
+/**
+ * @module plugins/auth/authzScope
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * 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 in them —
+ * by asking the authorization plugin in force, whichever one that is.
+ * @group Plugins
+ */
+import type { Express } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+export default class AuthzScope extends DmPlugin {
+    name: string;
+    roles: Role[];
+    /**
+     * Register `GET {api_prefix}/v1/authz/scope`.
+     *
+     * @param app Express application
+     */
+    api(app: Express): void;
+    /**
+     * The authorization plugin in force, if any.
+     *
+     * @returns the plugin, or undefined when the server is unrestricted
+     */
+    private authz;
+    /**
+     * Entities a client can create, as declared by the loaded plugins.
+     *
+     * @returns entity name and branch, one per creatable entity
+     */
+    private entities;
+    /**
+     * Answer the scope request.
+     *
+     * @param req Express request, carrying the authenticated user
+     * @param res Express response
+     */
+    private scope;
+    /**
+     * Read the display name and path of a branch, so a client can show the
+     * scope in the words the directory uses rather than as a raw DN.
+     *
+     * @param dn branch to describe
+     * @returns name and path when the entry carries them
+     */
+    private branchLabel;
+}

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

@@ -1,8 +1,37 @@
-import type { Response } from 'express';
+/**
+ * @module plugins/auth/llng
+ * @group Plugins
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * Lemonldap::NG authentication plugin
+ * This plugin enables authentication and authorization using Lemonldap::NG.
+ */
+import type { Express, Response } from 'express';
 import AuthBase, { DmRequest } from '../../lib/auth/base';
 import type { Role } from '../../abstract/plugin';
+type LlngHandler = typeof import('lemonldap-ng-handler');
 export default class AuthLLNG extends AuthBase {
     name: string;
     roles: Role[];
+    private handler?;
+    /**
+     * Load the optional `lemonldap-ng-handler` dependency before the server
+     * starts serving requests, rather than importing it statically.
+     *
+     * A static import would throw the moment this file is loaded — as soon as
+     * this plugin is configured — with Node's own opaque "Cannot find
+     * package" error. Loading it here instead means a server that never
+     * configures this plugin never touches the package at all, and one that
+     * does configure it gets a clear failure naming both the plugin and the
+     * missing dependency, at startup, instead of on the first request an auth
+     * plugin that cannot run must not pretend to succeed.
+     */
+    api(app: Express): Promise<void>;
+    /**
+     * Load the handler. Split out so tests can override it to simulate the
+     * dependency being absent, without actually uninstalling it.
+     */
+    protected loadHandler(): Promise<LlngHandler>;
     authMethod(req: DmRequest, res: Response, next: () => void): void;
 }
+export {};