ldap-rest 0.26.0 → 1.0.0

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

@@ -4,6 +4,7 @@ import type winston from 'winston';
 import pLimit from 'p-limit';
 import { type Config } from '../config/args';
 import { type DM } from '../bin';
+import type { Hooks } from '../hooks';
 import { type ChangeContext } from './changeContext';
 import { SchemaIndex } from './ldapSchema';
 export type AttributeValue = Buffer | Buffer[] | string[] | string;
@@ -14,15 +15,13 @@ export type { SearchOptions, SearchResult };
  * The directory as seen by one HTTP request.
  *
  * `ldapActions`'s own methods take the request as a trailing optional
- * argument, and the authorization plugins hook `ldap*request` and skip every
- * check when it is missing — so omitting it is an authorization bypass that
- * fails silently rather than loudly. Three shipped in the SCIM plugin alone.
+ * argument, which the authorization plugins judge by. One naming none is
+ * made for the request being served, if any (#385); this says which
+ * request is meant rather than leaving it to the context.
  *
  * These methods take no request parameter: it is captured once by
- * `ldapActions.forRequest()`, and forgetting it stops being expressible.
- * Request handlers should bind once and use this; the unbound methods remain
- * for work that genuinely belongs to no request, such as startup and cron
- * tasks, where passing nothing is the deliberate answer.
+ * `ldapActions.forRequest()`. Request handlers should bind once and use
+ * this; the server's own work goes through {@link ldapActions.system}.
  */
 export interface RequestBoundLdap {
     search(options: SearchOptions, base?: string): Promise<SearchResult | AsyncGenerator<SearchResult>>;
@@ -65,6 +64,8 @@ export interface ModifyOptions {
      */
     declaredClasses?: string[];
 }
+/** The request hooks an operation is judged in, see `ldapActions.authorize` */
+type AuthorizedHook = 'ldapaddrequest' | 'ldapmodifyrequest' | 'ldapdeleterequest' | 'ldaprenamerequest';
 declare class ldapActions {
     config: Config;
     options: ClientOptions;
@@ -106,6 +107,13 @@ declare class ldapActions {
     private schemaLoading?;
     /** Whether the last schema read failed, so a failure is logged once. */
     private schemaUnavailable;
+    /**
+     * How this server spells attribute names, by name in lower case: the
+     * configuration's, then the loaded schemas'. See {@link canonicalName}.
+     */
+    private spellings;
+    /** The first name given for each attribute type, to warn of another. */
+    private spelledTypes;
     /** Class problems already reported, per entry. See {@link warnOnce}. */
     private classWarnings;
     constructor(server: DM);
@@ -156,31 +164,91 @@ declare class ldapActions {
      * below it and the extra test costs nothing.
      */
     invalidateCache(dn: string): void;
+    /**
+     * Drop every cached read holding a value that names `dn`, or an entry
+     * below it.
+     *
+     * The directory mirrors some writes onto other entries than the one
+     * written: the `memberof` overlay keeps each member's `memberOf` in step
+     * with the group's `member` / `uniqueMember`, and `refint` rewrites or
+     * removes the references to an entry renamed or deleted. Those entries'
+     * cached reads are what {@link invalidateCache} cannot find, and they name
+     * the entry written: the members of a group name it in their `memberOf`.
+     * A member a write adds names it only once the write has landed; the
+     * caller drops those by their own DN.
+     *
+     * Every attribute is looked at, not `memberOf` alone: which attributes an
+     * overlay maintains is the deployment's configuration. A read naming `dn`
+     * for another reason is dropped too, which costs a miss.
+     */
+    private invalidateReferences;
     /**
      * The directory as the server itself, with no request behind it.
      *
-     * Every authorization plugin skips its check when a call carries no
-     * request, so an unbound call is a bypass — a deliberate one where the
-     * work belongs to nobody in particular: a startup task, a cron job, a
-     * uniqueness check, a referential-integrity check. Those must see the
+     * Every authorization plugin judges an operation by its request, and
+     * judges nothing without one. Some work belongs to nobody in particular:
+     * a startup task, a cron job, a uniqueness check, a referential-integrity
+     * check. Those must see the
      * whole directory to be correct: a caller who cannot *read* `uid=jdoe`
      * must still not be handed it as a free identifier, and a reference to an
      * organization they cannot read is still a valid reference.
      *
-     * The methods are the same objects as this instance's own — writes
-     * included, since a scheduled task writes: the examples above are reads
-     * because that is where the ambiguity lives, not because a write cannot
-     * belong to nobody. What this adds is a name: `ldap.system.search(…)` says
-     * the omission was meant, where `ldap.search(…)` says nothing and looks
-     * exactly like the mistake it takes one review to miss. A plugin serving a
-     * request should reach for {@link forRequest} instead.
+     * Writes included, since a scheduled task writes: the examples above are
+     * reads because that is where the ambiguity lives, not because a write
+     * cannot belong to nobody.
+     *
+     * While a request is being served, an operation that names none is made
+     * for it ({@link currentRequest}), so `ldap.search(…)` is judged as the
+     * caller. These operations step out of the request instead: they are the
+     * server's, whatever plugin serves the request — `authzDynamic` included.
+     * Each use says why the work is the server's.
+     *
+     * Only those six step out: `system.readableBy` and `system.forRequest`
+     * still judge the request they are given or find.
      */
     get system(): this;
+    /** {@link system}, built once. */
+    private systemView?;
     /**
      * Bind every directory operation to one request, so the authorization
      * hooks always see it. See {@link RequestBoundLdap}.
      */
     forRequest(req: Request): RequestBoundLdap;
+    /**
+     * Whether the caller of a request can read an entry.
+     *
+     * For a route that finds an entry as the server — by an attribute, across
+     * branches — and then answers about it: an entry the caller cannot read
+     * must get the answer an entry that is not there gets, or the route tells
+     * them what the directory holds where they cannot read. Refused or
+     * filtered out by an authorization plugin, the entry reads as absent.
+     * Without a request, as for any operation, nobody judges.
+     *
+     * @param dn the entry
+     * @param req the request whose caller asks
+     * @returns whether a read of the entry, as that caller, finds it
+     */
+    readableBy(dn: string, req?: Request): Promise<boolean>;
+    /**
+     * Have the authorization plugins judge an operation, without making it.
+     *
+     * A route that looks in the directory before it writes — whether an entry
+     * is there, which organization holds it, whether a pointer leads
+     * somewhere — answers what it found, as the server, to whoever asked. A
+     * caller who may not make the write then learns, one request at a time,
+     * what the directory holds where they cannot read. Judged first, they get
+     * the 403 the write itself would get, whether the entry is there or not.
+     *
+     * Only the hooks of the plugins with the `authz` role run, and what they
+     * return is dropped: the operation, when it is made, runs every hook
+     * again. Without a request in the arguments, the one being served is
+     * judged, as for the operation itself; outside any, nobody judges.
+     *
+     * @param hook the request hook the operation launches
+     * @param args what the operation hands that hook
+     * @throws the refusal of the first authorization plugin refusing
+     */
+    authorize<H extends AuthorizedHook>(hook: H, args: Parameters<NonNullable<Hooks[H]>>[0]): Promise<void>;
     /**
      * Declare the object classes an entity gives the entries of its branch.
      *
@@ -243,6 +311,55 @@ declare class ldapActions {
      * @returns indexed schema
      */
     schemaIndex(): Promise<SchemaIndex>;
+    /**
+     * Say how this server spells attribute names: a schema loaded by a plugin
+     * names its attributes as the plugins compare them. The first spelling of
+     * a name wins.
+     *
+     * @param names attribute names
+     */
+    knowAttributeNames(names: Iterable<string>): void;
+    /**
+     * Name each attribute of a write as this server does, in place.
+     *
+     * The directory takes `MAIL`, `rfc822Mailbox` and `0.9.2342.19200300.100.1.3`
+     * for `mail`, while the authorization plugins and the hooks look for
+     * `mail`: a write naming the organization link by its OID was judged as
+     * if it left the link alone. Each name is resolved through the directory
+     * schema — case, aliases, OIDs — and written as the configuration or a
+     * loaded schema spells it, or as the directory declares it first.
+     *
+     * An option names a value of its own (`member;lang-en` is not `member` to
+     * the hooks guarding `member`), and is refused, `;binary` aside. Two names
+     * for one attribute in one part of a write are refused too: on a modify
+     * the directory applies both, and only one would have been judged.
+     *
+     * Without the schema, the case is still set, and a name given as an OID,
+     * which nothing here could resolve, is refused.
+     *
+     * @param entry attributes of an add, or one part of a modify
+     * @throws BadRequestError on an option, or on one attribute named twice
+     */
+    canonicalAttributes(entry: AttributesList | undefined): Promise<void>;
+    /**
+     * {@link canonicalAttributes} for every part of a modify, in place.
+     *
+     * @param changes the modify
+     * @throws BadRequestError as {@link canonicalAttributes}
+     */
+    canonicalChanges(changes: ModifyRequest | undefined): Promise<void>;
+    /**
+     * The names of one part of a write, as {@link canonicalAttributes} writes
+     * them.
+     */
+    private canonicalNames;
+    /**
+     * One attribute description, named as this server does.
+     *
+     * @param key the name as written, options included
+     * @param index the directory schema, when it could be read
+     */
+    private canonicalName;
     /**
      * Hand a search result to `ldapsearchfilter`, which may drop entries the
      * caller is not allowed to see.
@@ -267,6 +384,10 @@ declare class ldapActions {
      * Move an entry to a new location (different parent)
      * Uses LDAP modifyDN with full DN to change both RDN and parent
      *
+     * Not judged, request or not: a move is the server's, made for a write
+     * already judged — the trash turning a delete into one. A route moving an
+     * entry for its caller uses {@link rename}, which is judged.
+     *
      * Note: ldapts provides a high-level API that accepts a full DN as the second parameter,
      * unlike the standard LDAP modifyDN which expects (newRDN, deleteOldRDN, newSuperior).
      * ldapts automatically parses the full DN and extracts the newRDN and newSuperior components

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

@@ -0,0 +1,41 @@
+/**
+ * @module lib/mailDomains
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * The mail domains a directory declares: entries in the domain branches,
+ * each naming its domain in an attribute.
+ * @group Libraries
+ */
+import type { DM } from '../bin';
+/** Where mail domain entries live, and the attribute naming their domain */
+export interface DomainBranch {
+    base: string;
+    attribute: string;
+}
+/** The mail domains among values, lower-cased as James stores them */
+export declare const mailDomains: (values: string[] | undefined) => string[];
+/**
+ * Where the mail domain entries live, and the attribute naming their
+ * domain: each loaded flat schema declaring the `domainName` role, the
+ * lookup `core/ldap/enterpriseRules` makes. Without one, the branch of the
+ * shipped `twake/nomenclature/twakeDomain.json` and the attribute
+ * `--enterprise-domain-name-attribute` names.
+ *
+ * Rebuilt on each call, as the enterprise rules do theirs: a list taken in
+ * a constructor could predate the schemas.
+ *
+ * @param server the server, whose flat entities are read
+ * @returns the domain branches
+ */
+export declare function domainBranches(server: DM): DomainBranch[];
+/**
+ * Every mail domain the domain branches declare, lower-cased.
+ *
+ * Read as the server: which domains the directory serves is not a matter of
+ * who asks. A branch that does not exist declares none; any other failure
+ * is thrown, since an answer missing domains reads as "not ours".
+ *
+ * @param server the server
+ * @returns the declared domains, each once
+ */
+export declare function declaredMailDomains(server: DM): Promise<string[]>;

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

@@ -0,0 +1,23 @@
+import type { Request } from 'express';
+/**
+ * Serve a request: what runs inside, synchronously or not, is made for it.
+ *
+ * @param req the authenticated request
+ * @param fn what serves it
+ * @returns what `fn` returns
+ */
+export declare function runForRequest<T>(req: Request, fn: () => T): T;
+/**
+ * Run something as the server, outside the request being served: its
+ * operations are judged by nobody. What `ldap.system` does.
+ *
+ * @param fn what to run
+ * @returns what it returns
+ */
+export declare function outsideRequest<T>(fn: () => T): T;
+/**
+ * The request being served.
+ *
+ * @returns the request, or undefined outside any, or as the server
+ */
+export declare function currentRequest(): Request | undefined;

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

@@ -147,7 +147,9 @@ export declare function unescapeDnValue(value: string): string;
 export declare function validateDnValue(value: string, fieldName: string): void;
 /**
  * Parse a Distinguished Name (DN) into its component parts (RDNs)
- * Handles escaped commas and other special characters
+ * Handles escaped commas and other special characters, and what OpenLDAP
+ * still reads from LDAPv2 (RFC 1779): `;` separating RDNs as `,` does, and
+ * a value in double quotes holding either
  *
  * @param dn - The DN to parse
  * @returns Array of RDN components
@@ -164,6 +166,15 @@ export declare function validateDnValue(value: string, fieldName: string): void;
  * @throws BadRequestError if `dn` is not a string
  */
 export declare function parseDn(dn: string): string[];
+/**
+ * Whether a string has the shape of a DN: RDNs of `type=value` assertions,
+ * a type being a name or an OID. What the directory would refuse as
+ * `invalidDNSyntax` is answered without asking it.
+ *
+ * @param dn - The string
+ * @returns whether it reads as a DN
+ */
+export declare function isDnSyntax(dn: string): boolean;
 /**
  * Extract the parent DN from a DN
  * Removes the first RDN component to get the parent branch
@@ -228,6 +239,32 @@ export declare function rdnValue(dn: string): string;
  * ```
  */
 export declare function isChildOf(dn: string, parentDn: string): boolean;
+/**
+ * Teach {@link normalizeDn} the names and OIDs of attribute types: each is
+ * read as the type's first name.
+ *
+ * @param types attribute types, as `ldapSchema` parses them
+ */
+export declare function registerAttributeTypes(types: Iterable<{
+    oid: string;
+    names: string[];
+}>): void;
+/**
+ * The name an attribute type is known by, spelled as declared, from the
+ * names and OIDs {@link registerAttributeTypes} was given: `COMMONNAME`,
+ * `2.5.4.3` and `OID.2.5.4.3` are `cn`.
+ *
+ * @param type attribute name or OID
+ * @returns the name, or undefined for a type it was not given
+ */
+export declare function knownAttributeName(type: string): string | undefined;
+/**
+ * The attribute types the first RDN of a DN names, as {@link normalizeDn}
+ * reads them: `CN=a+2.5.4.11=b,…` names `cn` and `ou`.
+ *
+ * @param dn the DN
+ */
+export declare function rdnTypes(dn: string): string[];
 /**
  * Normalize a DN into a canonical, comparable form.
  *
@@ -238,7 +275,9 @@ export declare function isChildOf(dn: string, parentDn: string): boolean;
  * `,`. Empty components (e.g. from a trailing separator) are dropped.
  *
  * This makes equality / suffix comparisons robust to case, surrounding
- * whitespace and multi-valued RDN ordering — unlike a raw string match.
+ * whitespace, multi-valued RDN ordering, the escapes a directory answers
+ * with ({@link canonicalValue}) and the names and OIDs of an attribute type
+ * ({@link registerAttributeTypes}) — unlike a raw string match.
  *
  * @param dn - The DN to normalize
  * @returns The canonical form

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

@@ -24,7 +24,6 @@
  * Sub-branch matching is used (a permission on `ou=acme` covers
  * `ou=users,ou=acme`).
  */
-import { AsyncLocalStorage } from 'async_hooks';
 import type { Express, Response } from 'express';
 import { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
@@ -51,16 +50,6 @@ export interface TokenEntry {
 export interface AuthzDynamicRequest extends DmRequest {
     authzToken?: TokenEntry;
 }
-/**
- * Per-request async context holding the authenticated token.
- *
- * Core plugins (ldapGroups, ldapFlat, etc.) do not always forward the Express
- * `req` object down to `ldapActions.search()` / `.modify()`. Relying solely
- * on `req` would therefore let un-tracked operations bypass authorization.
- * Using AsyncLocalStorage gives us a request-scoped, ambient handle that the
- * authz hooks can read regardless of whether the caller threaded `req`.
- */
-export declare const authzContext: AsyncLocalStorage<TokenEntry>;
 export default class AuthzDynamic extends AuthBase {
     name: string;
     roles: Role[];
@@ -175,7 +164,11 @@ export default class AuthzDynamic extends AuthBase {
      * request.
      */
     hooks: Hooks;
-    /** Read the active token from the async context, or (as a fallback) from `req`. */
+    /**
+     * The token of the request an operation is made for: the one it names,
+     * or the one being served (`ldapActions` fills it in). An operation the
+     * server makes as itself (`ldap.system`) has none, and is not judged.
+     */
     private activeToken;
     /**
      * Throw a ForbiddenError (403) if the token cannot perform `permission` on

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

@@ -82,8 +82,10 @@ export default class AuthzLinid1 extends AuthzBase {
      * Get list of branches user has access to
      */
     getAuthorizedBranches(userDn: string): Promise<string[]>;
+    /** The organizations naming the user an administrator */
+    ruleBranches(userDn: string): Promise<string[]>;
     /**
-     * Find permissions for a branch (supports sub-branch matching)
+     * The caller's rights on a branch: see {@link mostSpecificBranchRule}.
      */
     private findBranchPermissions;
 }

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

@@ -65,22 +65,18 @@ export default class AuthzPerBranch extends AuthzBase {
      * Get list of branches user has read access to (base class implementation)
      */
     getAuthorizedBranches(uid: string): Promise<string[]>;
+    /**
+     * The branches named by the user's rules and their groups'
+     */
+    ruleBranches(uid: string): Promise<string[]>;
     /**
      * Get list of branches user has access to for a given permission type
      */
     getAuthorizedBranchesForPermission(uid: string, permissionType: 'read' | 'write' | 'delete'): Promise<string[]>;
     /**
-     * Find permissions for a branch (supports sub-branch matching)
+     * The subject's rule on a branch: see {@link mostSpecificBranchRule}.
      */
     private findBranchPermissions;
-    /**
-     * Merge permissions (OR logic - grant if any source grants)
-     */
-    private mergePermissions;
-    /**
-     * Build LDAP filter for authorized branches
-     */
-    private buildBranchFilter;
     /**
      * The rules configured for a group, compared as DNs.
      *

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

@@ -51,8 +51,8 @@ export default class LdapAccountLifecycle extends DmPlugin {
      * @param entity flat entity holding the account
      * @param id identifier or DN of the entry
      * @param changes modification to apply
-     * @param req request this comes from: without it, every authorization
-     *   plugin built on `AuthzBase` skips its branch check
+     * @param req request this comes from, which the authorization plugins
+     *   judge the write by
      */
     private modify;
 }

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

@@ -25,11 +25,11 @@ import type { DM } from '../../bin';
  *       example: 42
  *     created:
  *       type: integer
- *       description: Entries successfully created (or counted in dry-run).
+ *       description: Entries successfully created (or that would be, in a dry run).
  *       example: 38
  *     updated:
  *       type: integer
- *       description: Existing entries updated.
+ *       description: Existing entries updated (or that would be, in a dry run).
  *       example: 2
  *     skipped:
  *       type: integer
@@ -58,7 +58,8 @@ import type { DM } from '../../bin';
  *             type: string
  *             description: |
  *               `unique` or `mailDomain`, with `attribute`, `value` and
- *               `domains`, as in the `Error` answer of a single write.
+ *               `domains`, as in the `Error` answer of a single write;
+ *               `forbidden` when the caller may not write the row.
  *           attribute: { type: string }
  *           value: { type: string }
  *           domains:
@@ -97,9 +98,33 @@ export default class LdapBulkImport extends DmPlugin {
      */
     private bulkImport;
     /**
-     * Process a single CSV record
+     * Whether the caller may write a row: create its entry, or change the one
+     * it names. Which of the two the row turns into is known only once the
+     * directory has been read, so the caller is judged first on both.
+     *
+     * The creation alone is not enough: judged by attachment, an entry is
+     * judged on the organization the row links it to, or on its parent when
+     * the row links it to none, while a change is judged on the organization
+     * it is attached to. An administrator updating their own accounts from a
+     * file naming no organization would be refused.
+     *
+     * No oracle: the change is judged on the entry as stored, and an entry
+     * that is not there is judged on its parent, as a creation without a link
+     * is.
+     *
+     * @throws the refusal of the creation when neither is allowed
      */
-    private processRecord;
+    private authorizeRow;
+    /**
+     * Build the entry of a CSV record, reading nothing from the directory: the
+     * write it makes is judged on it before anything is looked for.
+     */
+    private buildRecord;
+    /**
+     * Complete a record once its write has been judged: the organization path,
+     * read from the organization, then the required attributes.
+     */
+    private completeRecord;
     /**
      * Get editable attributes from schema (exclude fixed and calculated)
      */

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

@@ -214,11 +214,19 @@ export default class LdapEnterpriseRules extends DmPlugin {
      * compared by content, and the entry being updated is excluded from the
      * search — so re-sending an unchanged name no longer conflicts with itself.
      *
+     * Nor with its copies: a value the entry already holds, as stored, is not
+     * looked for again, or the copies other plugins keep of the entry — the
+     * applicative accounts of `appAccountsConsistency` carry its mail — would
+     * hold it against it. Held under another attribute, it is skipped only
+     * when that attribute's own constraint looked for it wherever this one
+     * looks: a value accepted under a narrower one is checked here.
+     *
      * @param entity entity the entry belongs to
      * @param name attribute being checked
      * @param attr its schema definition
      * @param values values submitted for it
-     * @param selfDn DN to exclude, on a modification
+     * @param dn entry being written
+     * @param current entry as stored, on a modification; its DN is excluded
      * @throws ConflictError naming the entry that already holds the value
      */
     private checkUnique;
@@ -341,6 +349,8 @@ export default class LdapEnterpriseRules extends DmPlugin {
      * @param dn DN to look for
      * @returns the matching entries, carrying that attribute
      */
+    /** The bases found missing, said once each */
+    private readonly missingBases;
     private searchReferrers;
     /**
      * Every reference the directory holds to a DN.

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

@@ -9,6 +9,12 @@ import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import { Hooks } from '../../hooks';
 import ldapActions from '../../lib/ldapActions';
+/**
+ * The domain of an address, as the managed domains are compared: after its
+ * last `@` (the local part may hold one, quoted), lower-cased, without the
+ * trailing dot DNS allows. Empty for an address without one.
+ */
+export declare const mailDomainOf: (mail: string) => string;
 export default class ExternalUsersInGroups extends DmPlugin {
     name: string;
     roles: Role[];
@@ -23,10 +29,21 @@ export default class ExternalUsersInGroups extends DmPlugin {
      * right under the branch. Null for any other member.
      */
     externalAddress(member: string): string | null;
-    /** `--mail-domain`, lower-cased: the domains no external member may use */
-    managedDomains(): string[];
+    /**
+     * The domains no external member may use, lower-cased: those of
+     * `--mail-domain` and those the directory declares in its domain branches,
+     * the ones `core/twake/james` follows. A deployment declaring its domains
+     * in the directory only would otherwise take an address of its own for an
+     * external one, and so would a client reading the list from `/config`.
+     *
+     * A subdomain of a managed domain is not managed: it is external unless
+     * declared itself.
+     */
+    managedDomains(): Promise<string[]>;
+    /** `--mail-domain`, lower-cased */
+    private configuredDomains;
     /**
      * Where a client sends an external member: `mail=<escaped address>,<branch>`
      */
-    getConfigApiData(): Record<string, unknown>;
+    getConfigApiData(): Promise<Record<string, unknown>>;
 }

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

@@ -164,6 +164,17 @@ export default class LdapGroups extends DmPlugin {
      * LDAP group methods
      */
     addGroup(cn: string, members?: string[], additional?: AttributesList, req?: Request): Promise<boolean>;
+    /**
+     * The entry `addGroup` writes, as the plugin's own hooks receive it. Built
+     * in one place, so that a creation judged before it is made — here, or by
+     * a plugin checking something first — is the creation made.
+     *
+     * @param cn the group's cn
+     * @param members member DNs
+     * @param additional attributes sent
+     * @returns the entry
+     */
+    candidateGroup(cn: string, members: string[], additional: AttributesList): AttributesList;
     modifyGroup(cn: string, changes: {
         add?: AttributesList;
         replace?: AttributesList;
@@ -239,7 +250,43 @@ export default class LdapGroups extends DmPlugin {
      * @returns LdapList (means Record<string, AttributesList> where key is the --ldap-user-main-attribute value [default: cn])
      */
     searchGroupsByName(cn: string, partial?: boolean, attributes?: string[], req?: Request): Promise<LdapList>;
-    protected fixDn(dn: string): string | false;
+    /**
+     * The DN of a group named by its `cn`, or given as a DN: one with a comma.
+     * A DN the directory would refuse is answered 400 rather than its error.
+     *
+     * @param cn the group's name, or its DN
+     * @returns its DN
+     */
+    protected toGroupDn(cn: string): string;
+    /**
+     * {@link toGroupDn} for a route serving the groups branch: what is not
+     * below it, nor named as these groups are (`cn=`), is no group of these
+     * routes, whatever entry it is (#395). The branch may be the whole
+     * directory, which is the default: the naming is what tells an account
+     * from a group there. A multi-valued RDN holding the main attribute
+     * passes here; the group class, checked next, is what settles it.
+     *
+     * @param cn the group's name, or its DN
+     * @returns its DN
+     */
+    protected routeGroupDn(cn: string): string;
+    /**
+     * A filter matching a group: one of the classes this plugin gives groups
+     * (`--group-class`), or a standard group class.
+     */
+    private groupFilter;
+    /**
+     * That the entry a route writes is a group, once the write is judged:
+     * another entry named alike is not one, and is not written as one (#395).
+     *
+     * Judged first, a caller who may not make the write gets the refusal
+     * whether the entry is there, a group or not; only one who may learns
+     * that it is none.
+     *
+     * @param dn the entry, from {@link routeGroupDn}
+     * @param judge the authorization of the write, as `ldap.authorize`
+     */
+    protected judgedGroup(dn: string, judge: () => Promise<void>): Promise<void>;
     /**
      * Verify that each member exists in LDAP
      *