ldap-rest 0.8.2 → 0.10.0

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

@@ -117,11 +117,41 @@ declare class ldapActions {
      * below it and the extra test costs nothing.
      */
     invalidateCache(dn: string): void;
+    /**
+     * 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
+     * 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.
+     */
+    get system(): this;
     /**
      * Bind every directory operation to one request, so the authorization
      * hooks always see it. See {@link RequestBoundLdap}.
      */
     forRequest(req: Request): RequestBoundLdap;
+    /**
+     * Hand a search result to `ldapsearchfilter`, which may drop entries the
+     * caller is not allowed to see.
+     *
+     * Applied on every return path of `search`, and deliberately after the
+     * cache: `ldapsearchresult` fires before caching and knows no request, so
+     * what it removed for one caller would be served to the next. A paginated
+     * search is filtered chunk by chunk, as it is consumed.
+     */
+    private filterForCaller;
     search(options: SearchOptions, base?: string, req?: Request): Promise<SearchResult | AsyncGenerator<SearchResult>>;
     /**
      * Wrap paginated search to ensure connection is released when done
@@ -142,8 +172,9 @@ declare class ldapActions {
      * @param dn - Current DN (e.g., "uid=user1,ou=users,dc=example,dc=com")
      * @param newDn - Full new DN (e.g., "uid=user1,ou=trash,dc=example,dc=com")
      *                ldapts will extract newRDN="uid=user1" and newSuperior="ou=trash,dc=example,dc=com"
+     * @param req - Request behind the move, when there is one
      */
-    move(dn: string, newDn: string): Promise<boolean>;
+    move(dn: string, newDn: string, req?: Request): Promise<boolean>;
     delete(dn: string | string[], req?: Request): Promise<boolean>;
     private setDn;
     opNumber(): number;

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

@@ -0,0 +1,28 @@
+/**
+ * @module lib/ldapCodes
+ *
+ * Reading an LDAP result code off a thrown error.
+ *
+ * Callers have to tell one failure from another — noSuchObject from
+ * entryAlreadyExists, a size limit from a server fault — and the code is the
+ * only part of a failure the protocol defines. The wording is the driver's,
+ * and no driver promises to keep it.
+ *
+ * This lived in `plugins/scim/errors` until an LDAP plugin needed it too;
+ * nothing in it is SCIM's business, so it is here and SCIM re-exports it.
+ *
+ * @group Libraries
+ */
+/**
+ * Extract an LDAP numeric error code from a thrown ldapts error.
+ *
+ * `.code` first: ldapts sets it, and `ldapActions` carries it across its own
+ * wrapping rather than reducing the failure to a sentence. The message
+ * patterns below stay as a fallback for the paths that still throw a bare
+ * `Error` — they are why a driver that reworded its messages could quietly
+ * turn a 400 into a 500, so they are the last resort, not the first.
+ *
+ * @param err whatever was thrown
+ * @returns the LDAP result code, or undefined when nothing says
+ */
+export declare function extractLdapCode(err: unknown): number | undefined;

package/dist/src/lib/storage/store.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @module lib/storage/store
+ *
+ * A small keyed store, and what every backend of it shares.
+ *
+ * What a consumer gets is deliberately thin: a key, a value, a deadline, and
+ * the promise that the value stops being returned once that deadline passes.
+ * Nothing here knows why a record exists — Back-Channel Logout tombstones
+ * were the first use, a refresh-token lock and a shared counter are the ones
+ * in sight, and none of them is this layer's business.
+ *
+ * Two rules the backends do not get to reinterpret:
+ *
+ *  - **Expiry is enforced on read.** Not every backend can expire a record by
+ *    itself, and the one that can (Valkey's TTL) must still agree with the
+ *    others about when a record died. A sweeper running late is then a
+ *    storage cost, never a wrong answer.
+ *  - **The deadline belongs to the consumer.** How long a record lives is the
+ *    policy of whoever wrote it; the store is told an instant and respects
+ *    it. A backend deciding for itself is how four of them come to disagree
+ *    about the same question.
+ *
+ * Keys are namespaced so two consumers cannot collide in one LDAP branch or
+ * one directory.
+ *
+ * @group Libraries
+ */
+import type winston from 'winston';
+/** What a backend keeps: a value, and when it stops counting. */
+export interface StoredRecord {
+    value: string;
+    deadline: number;
+}
+export default abstract class Store {
+    /** Name of the backend, for the log lines it writes. */
+    abstract name: string;
+    protected logger: winston.Logger;
+    private sweeper?;
+    constructor(logger: winston.Logger);
+    /** Read one record, or null when nothing is kept under this key. */
+    protected abstract load(key: string): Promise<StoredRecord | null>;
+    /** Write one record, replacing whatever was there. */
+    protected abstract save(key: string, record: StoredRecord): Promise<void>;
+    /** Drop one key. A key that is not there is not an error. */
+    protected abstract drop(key: string): Promise<void>;
+    /** Drop every expired record. Returns how many went. */
+    abstract sweep(): Promise<number>;
+    /**
+     * The key a backend actually sees, namespaced so two consumers cannot
+     * collide.
+     *
+     * Joined on NUL, not on a colon: `('bcl', 'x:y')` and `('bcl:x', 'y')`
+     * would otherwise be the same string, and one record would answer for
+     * both. A consumer picks its namespace in code, so a colon in one is
+     * unlikely — but for a store about to hold session state, holding by
+     * construction beats holding by convention. `lib/ldapActions` moved its own
+     * cache keys to NUL for the same reason.
+     */
+    protected static scoped(namespace: string, key: string): string;
+    /** The same pair, for a human reading a record. Never used to look one up. */
+    protected static readable(scoped: string): string;
+    /**
+     * The value kept under this key, or null.
+     *
+     * A record past its deadline is not one: it is dropped and answered as
+     * absent, whatever the sweeper has or has not done. Consumers rely on this
+     * — a Back-Channel Logout mark that outlives its session would keep out a
+     * person who has since logged in again.
+     */
+    get(namespace: string, key: string): Promise<string | null>;
+    /** Keep `value` under this key until `deadline`, an epoch in milliseconds. */
+    set(namespace: string, key: string, value: string, deadline: number): Promise<void>;
+    /** Forget this key. */
+    delete(namespace: string, key: string): Promise<void>;
+    /**
+     * Run the sweeper every `seconds`, and once now.
+     *
+     * Unreferenced, so a server with nothing else to do still exits, and a
+     * sweep that fails warns rather than taking the server with it: reads
+     * enforce expiry anyway, so the cost of a failed sweep is storage.
+     */
+    startSweeping(seconds: number): void;
+    stopSweeping(): void;
+}

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

@@ -22,6 +22,25 @@ export declare function getCompiledRegex(pattern: string, flags?: string): RegEx
  */
 export declare function escapeRegex(str: string): string;
 export declare const launchHooks: (hooks: Function[] | undefined, ...args: unknown[]) => Promise<void>;
+/**
+ * Record the plugin a hook function belongs to.
+ *
+ * @param fn the registered function
+ * @param plugin the plugin's instance name
+ * @param hook the hook it is registered under
+ */
+export declare const recordHookOwner: (fn: Function, plugin: string, hook: string) => void;
+/**
+ * The plugin a hook function belongs to, and the hook it is registered
+ * under, when `registerPlugin` registered it.
+ *
+ * @param fn a hook function
+ * @returns its plugin's instance name and hook name, or undefined
+ */
+export declare const hookOwner: (fn: Function) => {
+    plugin: string;
+    hook: string;
+} | undefined;
 export declare const launchHooksChained: <T>(hooks: Function[] | undefined, args: T) => Promise<T>;
 export declare const transformSchemas: (schemas: string | Buffer, config: Config) => string;
 /**

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

@@ -92,6 +92,82 @@ export default class AuthzDynamic extends AuthBase {
      * during an outage.
      */
     private ensureFresh;
+    /**
+     * Whether this request is allowed past the token ACLs without a token.
+     *
+     * The plugin used to step aside as soon as anything else had set
+     * `req.user`, which is not a decision anyone wrote down: with
+     * `core/auth/token` and this plugin both unscoped, the dispatcher runs the
+     * token plugin first, it sets `req.user`, and every LDAP operation of that
+     * request was then checked against no ACL at all — a branch-unrestricted
+     * administrator. Registered the other way round, the same configuration
+     * demanded both credentials. An ordering accident decided which.
+     *
+     * The comment that justified it named `trustedProxy + authzDynamic`, a
+     * composition that never worked: `trustedProxy` sets `req.trustedProxy`
+     * and `req.proxyAuthUser`, never `req.user`, so that pair never took this
+     * path — while every authenticator that does set it, did.
+     *
+     * So the bypass is named now. `--authz-dynamic-bypass` lists the
+     * identities that may skip the ACLs, plus `trusted-proxy` for the
+     * composition the comment meant and `any-authenticated` for the old
+     * behaviour, which a deployment relying on it can ask for in one line.
+     *
+     * @param req request being authenticated
+     * @returns what allowed it past, or undefined when nothing does
+     */
+    private bypassReason;
+    /**
+     * Say, once and at startup, when a configuration is ambiguous.
+     *
+     * The dispatcher runs every authenticator claiming the winning prefix, so
+     * this plugin sharing one with another means each request carries two
+     * verdicts — and, before the bypass was named, which of them decided the
+     * ACLs depended on registration order. A deployment reading as "tokens are
+     * scoped to their tenant's branches" deserves to hear that on the first
+     * line of its log rather than from an incident.
+     */
+    protected identitySource(): string;
+    afterLoad(): void;
+    /**
+     * The verdict `authMethod` could not reach on its own.
+     *
+     * A bypass is written in terms of the identity another authenticator
+     * publishes, and the dispatcher runs them in registration order: asked
+     * first, this plugin sees no identity yet and would refuse the very
+     * request the bypass is for — order deciding the answer again, which is
+     * the shape of the bug this fixes. So `authMethod` defers, and the
+     * dispatcher calls this once every authenticator has run and before any
+     * route: `req.user` is final here, and nothing has answered yet.
+     *
+     * A middleware of our own would not do. `api()` runs during registration,
+     * and this plugin is not in `priority.json` — nor could it be, since a
+     * named instance is matched by exact string and falls back into the
+     * parallel batch — so the middleware would land wherever this plugin fell
+     * among the others, and a route plugin registered first would answer
+     * before the refusal.
+     *
+     * @param req request whose verdict was deferred
+     * @param res response, ended when the request is refused
+     * @param next continuation, called when it is allowed
+     */
+    afterChain(req: DmRequest, res: Response, next: () => void): void;
+    /**
+     * Refuse a request carrying no token of ours — unless a bypass may cover
+     * it, in which case the verdict waits for the rest of the chain.
+     *
+     * A bypass names the identity another authenticator publishes, and the
+     * dispatcher runs them in registration order: asked first, this plugin
+     * sees no identity yet, and refusing there would make the answer depend on
+     * that order again. So the request is marked and the middleware mounted in
+     * `api()` decides, after every authenticator has run.
+     *
+     * @param req request with no usable token
+     * @param res response, ended when the request is refused
+     * @param next continuation, called when the verdict is deferred
+     * @param warning what to log when it is refused outright
+     */
+    private refuseOrDefer;
     authMethod(req: DmRequest, res: Response, next: () => void): void;
     /**
      * Authorization hooks. These run after the auth middleware has populated

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

@@ -23,6 +23,12 @@ export default class AuthzLinid1 extends AuthzBase {
     resolveUser(uid: string): Promise<string | null>;
     /**
      * Get user DN from uid
+     *
+     * An identity naming several entries is refused (`AmbiguousIdentityError`)
+     * rather than answered with `null`: under `--authz-unresolved-user allow`,
+     * `null` means "skip authorization", so an ambiguous directory would open
+     * every branch. A failed search propagates for the same reason — it used
+     * to read as `null` too, and `resolveCaller` then cached it.
      */
     getUserDn(uid: string): Promise<string | null>;
     /**

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

@@ -7,6 +7,7 @@
  * @group Plugins
  */
 import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
 import type { AuthConfig, BranchPermissions } from '../../config/args';
 import type { DmRequest } from '../../lib/auth/base';
 import AuthzBase from '../../lib/authz/base';
@@ -18,11 +19,40 @@ export default class AuthzPerBranch extends AuthzBase {
     name: string;
     authConfig?: AuthConfig;
     groupCache: Map<string, CachedGroups>;
+    /** Lookups under way, so concurrent misses for one uid share a search. */
+    private pendingGroups;
+    /**
+     * Bumped by every invalidation. A lookup that started before a write may
+     * have read the directory before it: it still answers its own callers,
+     * but does not put what it read back into the cache.
+     */
+    private groupGeneration;
+    /** `authConfig.groups` keyed by normalized DN, and the object it was built from. */
+    private groupRulesIndex?;
+    hooks: AuthzBase['hooks'] & Pick<Hooks, 'ldapadddone' | 'ldapmodifydone' | 'ldapdeletedone'>;
     constructor(server: DM);
+    /**
+     * Whether a modify can change which groups a uid belongs to: it touches
+     * the member attribute, or the attribute a uid is resolved by.
+     */
+    private touchesMembership;
+    /** Drop every cached and pending group lookup. */
+    forgetGroups(): void;
     /**
      * Resolve user - for authzPerBranch, we use uid directly
      */
     resolveUser(uid: string): Promise<string | null>;
+    /**
+     * Say, once every plugin is loaded, when no configured user can ever be
+     * the caller.
+     *
+     * A `authz_per_branch_config.users` key is an identity, and which values
+     * an authenticator publishes differs per plugin: keys written for token
+     * names are inert behind OpenID Connect, where the identity is a `sub`.
+     * The permissions then fall back to `default`, which reads as a
+     * configuration that is working.
+     */
+    afterLoad(): void;
     /**
      * Override to add authConfig check
      */
@@ -51,9 +81,25 @@ export default class AuthzPerBranch extends AuthzBase {
      * Build LDAP filter for authorized branches
      */
     private buildBranchFilter;
+    /**
+     * The rules configured for a group, compared as DNs.
+     *
+     * The directory answers with its own spelling of a group's DN, and the
+     * configuration carries whatever an administrator typed: a textual lookup
+     * missed `cn=Admins,ou=Groups,…` against `cn=admins, ou=groups,…` and
+     * dropped the rule without a word. The index is rebuilt whenever
+     * `authConfig.groups` is replaced.
+     */
+    private groupRules;
     /**
      * Get user's group memberships with caching
+     *
+     * Concurrent misses for one uid share a single lookup. What the lookup
+     * found is cached, including "no group"; a failed search is not, so an
+     * outage does not outlive itself by a TTL.
      */
     getUserGroups(uid: string): Promise<string[]>;
+    /** Read a uid's group memberships from the directory. */
+    private lookupGroups;
 }
 export {};

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

@@ -14,9 +14,35 @@ export default class AuthzPerRoute extends DmPlugin {
     name: string;
     roles: Role[];
     private rules;
+    /** Said once: a rule keyed on a value the authenticator did not publish. */
+    private fallbackWarned;
+    /** Routes already reported as reached with no identity. */
+    private unidentifiedRoutes;
+    /** How many such lines have been written at `warn`. */
+    private unidentifiedWarnings;
+    /**
+     * How many of those lines to write, and how many routes to remember.
+     *
+     * The bound that matters is on the *log*, not on the set: `req.path` is a
+     * concrete path, identifiers included, so a client decides how many
+     * distinct ones exist. Bounding only the set leaves every path it never
+     * had room for unseen for ever, and each request for one writes the line
+     * again — the bound holds the memory and loses the thing it was there to
+     * protect.
+     */
+    private static readonly UNIDENTIFIED_MAX;
     constructor(...args: ConstructorParameters<typeof DmPlugin>);
     private parseEntry;
     private addRule;
     private matches;
+    /**
+     * Say, once every plugin is loaded, when no rule can ever match.
+     *
+     * The rules are keyed on identities, and which values an authenticator
+     * publishes is the whole subject of #187: a rule written for a token name
+     * is inert behind OpenID Connect, where the identity is a `sub`. Inert is
+     * the part worth a line — nothing is refused, so nothing looks wrong.
+     */
+    afterLoad(): void;
     api(app: Express): void;
 }

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

@@ -24,11 +24,52 @@ export default class AuthzScope extends DmPlugin {
      */
     api(app: Express): void;
     /**
-     * The authorization plugin in force, if any.
+     * Whether a plugin can say who may do what where.
      *
-     * @returns the plugin, or undefined when the server is unrestricted
+     * The `authz` role says a plugin restricts something, not that it can
+     * answer that: `authzPerRoute` gates URLs and `authzDynamic` reads a token,
+     * and neither resolves a user or a branch. Both carry the role, and
+     * `authzPerRoute` sits in priority.json, so it is registered before any
+     * branch-level plugin — picking by role alone made this endpoint answer 500
+     * to every caller on any server combining the two. The capability is what
+     * is asked for.
+     *
+     * @param plugin a loaded plugin
+     * @returns true when it resolves users and reads branch permissions
+     */
+    private static canDescribe;
+    /** @returns the loaded plugins able to describe a scope, in load order */
+    private describers;
+    /**
+     * Whether a plugin judges this request.
+     *
+     * One that authenticates too — `authzDynamic` — judges the requests it
+     * vouched for, which carry its token; the others, the requests of the
+     * authenticators `--authz-for` gives them, and only when they carry an
+     * identity: an anonymous request passes every one of them.
+     *
+     * @param plugin an authorization plugin
+     * @param req the request
+     * @returns true when the plugin's verdict applies to it
+     */
+    private static judges;
+    /**
+     * Refuse a `--authz-scope-source` naming nothing that can describe a scope.
+     *
+     * Read leniently, a typo would fall back to the first plugin loaded, which
+     * is the choice the option exists to take away from load order.
+     */
+    assertComposition(): void;
+    /**
+     * Say, at startup, when the scope depends on which plugin loaded first.
+     *
+     * Two plugins able to describe a scope, both judging one caller, is two
+     * models of what that caller may do; the hooks apply both, and this
+     * endpoint can only describe one. Without `--authz-scope-source` it is
+     * the first loaded — import-completion order for plugins outside
+     * priority.json, which is not a decision anyone took.
      */
-    private authz;
+    afterLoad(): void;
     /**
      * Entities a client can create, as declared by the loaded plugins.
      *

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

@@ -2,6 +2,8 @@ import type { Response } from 'express';
 import AuthBase, { type DmRequest } from '../../lib/auth/base';
 import type { Role } from '../../abstract/plugin';
 export default class AuthHmac extends AuthBase {
+    protected knownIdentities(): string[];
+    protected identitySource(): string;
     name: string;
     roles: Role[];
     private services;

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

@@ -32,6 +32,45 @@ export default class AuthLLNG extends AuthBase {
      * dependency being absent, without actually uninstalling it.
      */
     protected loadHandler(): Promise<LlngHandler>;
+    /**
+     * The header the handler writes the identity to.
+     *
+     * `lemonldap-ng-handler` 3.x assigns it with that exact spelling —
+     * `req.headers["Lm-Remote-User"] = session[this.tsv.whatToTrace]` in its
+     * `sendHeaders` — while Node lower-cases every header that arrives on the
+     * wire. The two never collide, which is what keeps a client from
+     * supplying its own identity, and nothing in either project promises that
+     * spelling: `dropForgedIdentity` below removes what a client sent, so the
+     * plugin can then read whatever case the handler used.
+     */
+    private static readonly USER_HEADER;
+    /**
+     * Remove any identity header the request arrived with.
+     *
+     * Only the handler may name the caller. A client sending
+     * `Lm-Remote-User: admin` reaches this plugin as `lm-remote-user`, and the
+     * read below is case-insensitive, so without this it would be read as an
+     * identity the handler never vouched for.
+     *
+     * @param req incoming request, whose headers are pruned in place
+     */
+    private static dropForgedIdentity;
+    /**
+     * A header's value, whatever case it was written in.
+     *
+     * @param req request the handler has just passed on
+     * @param lowercased the header's name, already lower-cased
+     * @returns its value, or undefined when it is not there
+     */
+    private static headerValue;
+    /**
+     * The identity the handler vouched for, whatever case it wrote it in.
+     *
+     * @param req request the handler has just passed on
+     * @returns the identity, or undefined when the handler named nobody
+     */
+    private static vouchedIdentity;
+    protected identitySource(): string;
     authMethod(req: DmRequest, res: Response, next: () => void): void;
 }
 export {};

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

@@ -1,11 +1,74 @@
 import type { Express, Response } from 'express';
-import { DmRequest } from '../../lib/auth/base';
-import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { ConfigParams } from 'express-openid-connect';
+import AuthBase, { DmRequest } from '../../lib/auth/base';
+import { type Role } from '../../abstract/plugin';
 import { DM } from '../../bin';
-export default class OpenIDConnect extends DmPlugin {
+export default class OpenIDConnect extends AuthBase {
     name: string;
     roles: Role[];
+    /** The library's router, built once: `auth()` returns a fresh one per call. */
+    private router?;
     constructor(server: DM);
+    /**
+     * What is handed to `express-openid-connect`.
+     *
+     * Built apart from `api` so it can be looked at: leaving `onLogin` out of
+     * `backchannelLogout` made the library run its own, which reaches for a
+     * store nothing configured here and threw on every callback — a 500 on
+     * every login, with the session cookie already set.
+     */
+    buildConfig(): ConfigParams;
+    protected identitySource(): string;
+    /**
+     * Paths this authentication claims.
+     *
+     * Its own routes come with it. Scoped to `/api/admin`, the plugin would
+     * otherwise leave `/callback` to whatever else guards the server — a
+     * catch-all token plugin answering the provider's redirect with a 401 —
+     * so the four are claimed too, which also keeps them out of every other
+     * plugin's catch-all.
+     *
+     * Unscoped, the plugin already guards everything and the list stays empty.
+     *
+     * @returns the prefixes the dispatcher routes here
+     */
+    get pathPrefixes(): string[];
+    /**
+     * Register with the dispatcher, like every other authentication plugin.
+     *
+     * This plugin used to mount three layers of its own — the `beforeAuth`
+     * hooks, the library's router, then the identity — which kept their
+     * registration order. An instance carrying a name, the only form that can
+     * hold `auth_path_prefix`, landed in the parallel batch and mounted after
+     * the plugins that were supposed to read what it publishes: with
+     * `core/auth/authzPerRoute` loaded, every rule was judged before
+     * `req.user` existed, and `authzPerRoute` passes a request it cannot
+     * identify. The rules read as enforced and were inert.
+     *
+     * The dispatcher is mounted before any plugin can register a route, runs
+     * only the plugin whose claim is most specific, and hands `authMethod`
+     * the `beforeAuth`/`afterAuth` hooks — the three layers, in a place where
+     * order is not a configuration accident. (`afterAuth` used to be gated on
+     * a flag nothing sets, so this plugin's own copy of it never ran either.)
+     *
+     * @param app the express application
+     */
     api(app: Express): void;
+    /**
+     * Read the session, then require one.
+     *
+     * `requiresAuth()` runs *after* the router, so `req.oidc` exists when the
+     * decision is taken. It redirects a browser to the provider and answers
+     * 401 to an API client, which is the library's default and what makes a
+     * login work at all; the other authentication plugins answer JSON 401
+     * throughout, and that difference is documented rather than smoothed over.
+     *
+     * The plugin's own routes never reach the second step: the router answers
+     * them itself.
+     *
+     * @param req incoming request
+     * @param res response, ended by the library when it refuses or redirects
+     * @param next called once the request carries an identity
+     */
     authMethod(req: DmRequest, res: Response, next: () => void): void;
 }

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

@@ -6,7 +6,9 @@
  * to protect against brute-force attacks. It should be loaded BEFORE auth plugins.
  *
  * Uses an Express middleware to check rate limits before processing, and
- * an afterAuth hook to track failed authentication attempts.
+ * a middleware per request. It describes an `afterAuth` hook tracking failed
+ * authentication attempts, which it has never registered — the counting is
+ * per request, whatever the request turns out to be.
  *
  * @author Xavier Guimard <xguimard@linagora.com>
  */

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

@@ -9,6 +9,8 @@ import type { Response } from 'express';
 import AuthBase, { type DmRequest } from '../../lib/auth/base';
 import type { Role } from '../../abstract/plugin';
 export default class AuthToken extends AuthBase {
+    protected knownIdentities(): string[];
+    protected identitySource(): string;
     name: string;
     roles: Role[];
     private tokenMap;

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

@@ -2,6 +2,8 @@ import type { Response } from 'express';
 import AuthBase, { type DmRequest } from '../../lib/auth/base';
 import type { Role } from '../../abstract/plugin';
 export default class AuthTotp extends AuthBase {
+    protected knownIdentities(): string[];
+    protected identitySource(): string;
     name: string;
     roles: Role[];
     private totpUsers;