ldap-rest 0.8.1 → 0.9.0

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/authzPerBranch.d.ts

@@ -23,6 +23,17 @@ export default class AuthzPerBranch extends AuthzBase {
      * 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
      */

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;

package/dist/src/plugins/bcl.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @module plugins/bcl
+ *
+ * Back-Channel Logout: what a provider tells us is dead, and what we do with
+ * it on the next request.
+ *
+ * Nothing here stores a session. `core/auth/openidconnect` keeps that in its
+ * cookie; a logout token only leaves a **tombstone** saying that one `sid`, or
+ * every session of one `sub`, is dead, and each request asks whether such a
+ * mark exists. Recording only what is dead is what keeps the sessions
+ * stateless and the storage small.
+ *
+ * Where the marks live is `core/storage`'s business, not this plugin's. What
+ * stays here is the policy: which keys a token kills, how long a mark is
+ * kept, and what a login forgets.
+ *
+ * @group Plugins
+ */
+import DmPlugin from '../abstract/plugin';
+import type { DM } from '../bin';
+import type { OidcLogoutToken, OidcSessionClaims } from '../hooks';
+export default class Bcl extends DmPlugin {
+    name: string;
+    dependencies: {
+        storage: string;
+    };
+    private storage?;
+    /** How long a tombstone is kept, in milliseconds. */
+    private retention;
+    constructor(server: DM);
+    /**
+     * Take hold of the store.
+     *
+     * Deliberately not the constructor. A plugin is built before
+     * `registerPlugin` reads its `dependencies` and loads what they name, so a
+     * constructor asking for the store answers for the order of two `--plugin`
+     * arguments rather than for the configuration: `core/bcl` listed first
+     * would be refused for a storage that is right there, and the declaration
+     * above — the thing meant to make order irrelevant — would have loaded it
+     * a moment later. `api()` runs after that loop, which is where
+     * `requirePlugin`'s own promise starts holding.
+     */
+    api(): void;
+    /**
+     * The store, once `api()` has taken hold of it.
+     *
+     * `registerPlugin` calls `api()` before it subscribes anything, so a hook
+     * running without one means a plugin built by hand and never registered —
+     * a test, in practice. Saying so beats reading `undefined` as "nothing is
+     * recorded", which is the fail-open this plugin exists to prevent.
+     */
+    private get store();
+    /**
+     * The keys a token kills.
+     *
+     * A provider sends `sid`, or `sub`, or both: `sid` ends one session, `sub`
+     * ends every session of that person.
+     */
+    private static keys;
+    hooks: {
+        oidclogouttoken: (token: OidcLogoutToken) => Promise<void>;
+        oidclogin: (claims: OidcSessionClaims) => Promise<void>;
+        oidcsessionvalid: ([claims, valid]: [OidcSessionClaims, boolean]) => Promise<[OidcSessionClaims, boolean]>;
+    };
+}

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

@@ -139,6 +139,80 @@ export default class LdapOrganizations extends DmPlugin {
     getOrganisationTop(req?: Request): Promise<AttributesList | AttributesList[]>;
     getOrganisationByDn(dn: string, req?: Request): Promise<AttributesList>;
     getOrganisationSubnodes(dn: string, req?: Request): Promise<AttributesList[]>;
+    /** Nodes already warned about, so a crowded tree says it once per node. */
+    private sizeLimitWarned;
+    /** How many of them to remember. */
+    private static readonly SIZE_LIMIT_WARNED_MAX;
+    /**
+     * Say once per node what only the directory can fix.
+     *
+     * A console expanding a tree lists the same crowded node on every refresh,
+     * and a warning per listing buries the rest of the log while saying
+     * nothing new: the answer stays partial until someone raises the size
+     * limit. The first listing carries the message, the others go to `debug`.
+     *
+     * The set is bounded, so a directory with thousands of crowded nodes
+     * cannot grow it without end. Past the bound the message is written every
+     * time — the loud side of the trade rather than the silent one.
+     *
+     * @param key node the message is about
+     * @param message what to say
+     */
+    private warnSizeLimit;
+    /**
+     * The child organizations of a node, and what to do when the directory
+     * will not list them all.
+     *
+     * Every failure used to be read as "no children" (#179): the node's own
+     * children were searched without a limit, and a directory answering
+     * `sizeLimitExceeded` rather than a long list left the endpoint returning
+     * `200 []` with nothing above `debug` to say so. An empty tree is what a
+     * console then draws for a branch holding a thousand organizations.
+     *
+     * Three outcomes, and only one of them is emptiness:
+     *
+     *  - `noSuchObject` (32): nothing is there. An empty answer is the truth.
+     *  - `sizeLimitExceeded` (4): the answer was longer than the server's
+     *    limit. Measured against OpenLDAP 2.5, the paged control does not lift
+     *    it — `size.prtotal` bounds the whole search, so a paged walk ends on
+     *    the same refusal. What does change the answer is asking for a bounded
+     *    number: ldapts raises the refusal only when the request carried no
+     *    `sizeLimit` of its own, so a second, bounded search comes back with
+     *    entries where the first came back with an error. The answer then says
+     *    it is partial, through the `moreIndicator` row the attached entries
+     *    already use.
+     *  - anything else is a failure, and answering `[]` to a failure is how a
+     *    broken directory comes to look exactly like an empty one.
+     *
+     * The first search is paged for the directories where paging *is* what
+     * lifts the limit: Active Directory answers an unpaged search with at most
+     * `MaxPageSize` entries and expects the control for the rest.
+     *
+     * @param dn organization whose children are wanted
+     * @param filter what those children have to match
+     * @param cap how many to keep when the directory will not list them all
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns the children, followed by a `moreIndicator` row when the
+     *          directory refused to list them all
+     */
+    private childOrganizations;
+    /**
+     * The entries attached to an organization without being one.
+     *
+     * Capped at `cap`, with a `moreIndicator` row counting what was left out —
+     * the behaviour this endpoint already had, plus the refusal the children
+     * search just learned to survive: a directory that will not walk the whole
+     * link filter is told about rather than turned into an empty list.
+     *
+     * @param baseDn branch the attached entries live in
+     * @param filter what links them to the organization
+     * @param cap how many to return
+     * @param dn organization they are attached to, for the indicator's DN
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns the entries, followed by a `moreIndicator` row when some were
+     *          left out
+     */
+    private linkedEntities;
     addOrganization(dn: string, entry: AttributesList, req?: Request): Promise<boolean>;
     modifyOrganization(dn: string, changes: ModifyRequest): Promise<boolean>;
     validateNewOrganization(dn: string, entry: AttributesList): Promise<boolean>;
@@ -168,7 +242,22 @@ export default class LdapOrganizations extends DmPlugin {
         newDn: string;
     }>;
     deleteOrganization(dn: string): Promise<boolean>;
-    searchOrganisationSubnodes(dn: string, query: string): Promise<AttributesList[]>;
+    /**
+     * The same two searches as `getOrganisationSubnodes`, narrowed by a query.
+     *
+     * Both go through the helpers that classify a failure rather than reading
+     * every one of them as emptiness (#179), and both now carry the request:
+     * they ran without one, and an authorization plugin skips its check when
+     * there is none — the same gap the flat routes had until 0.8.2. The
+     * attached entries are capped like the other endpoint's, since an answer
+     * the directory refuses to finish is what this is about.
+     *
+     * @param dn organization to search under
+     * @param query what to look for in a name, a description or an identity
+     * @param req incoming request, forwarded to the authorization hooks
+     * @returns matching organizations then matching attached entries
+     */
+    searchOrganisationSubnodes(dn: string, query: string, req?: Request): Promise<AttributesList[]>;
     /**
      * Provide configuration for config API
      */

package/dist/src/plugins/scim/baseResolver.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from '../../config/args';
-import type { DmRequest } from '../../lib/auth/base';
+import { type DmRequest } from '../../lib/auth/base';
 export interface BaseMapEntry {
     userBase?: string;
     groupBase?: string;
@@ -14,6 +14,8 @@ export declare class BaseResolver {
     private readonly userBaseHeader;
     private readonly groupBaseHeader;
     private readonly headerRoot;
+    /** Kept so a base is keyed on whatever `--authz-identity` names. */
+    private readonly config;
     constructor(config: Config);
     private applyTemplate;
     /** Read a request header by name, tolerating Express req or a plain object. */