ldap-rest 0.8.2 → 0.9.0

package/dist/src/lib/auth/base.d.ts

@@ -1,8 +1,32 @@
 import type { Express, Request, Response } from 'express';
+import DmPlugin from '../../abstract/plugin';
+import type { Config } from '../../config/args';
+/**
+ * A request as the authentication plugins leave it.
+ *
+ * `user` is what an authorization rule is keyed on, and every authenticator
+ * fills it with something different — a token's name, an OIDC `sub`, a
+ * tenant. `userName` is the same caller under the name a person would use
+ * for them, so a rule can be written once and survive a change of
+ * authenticator; `--authz-identity` says which of the two the authorization
+ * plugins read, and the default stays `user`, which changes nothing for an
+ * existing deployment.
+ */
 export type DmRequest = Request & {
     user?: string;
+    userName?: string;
+    /**
+     * The authentication plugins that vouched for this request, by instance
+     * name, in the order the dispatcher ran them.
+     *
+     * Written by the dispatcher alone, once a plugin has let the request
+     * through, so an authorization plugin can tell *whose* request it is
+     * looking at: a machine token and an administrator's session carry
+     * identities from different models, and a rule written for one of them
+     * is not a judgement about the other (`--authz-for`).
+     */
+    authenticators?: string[];
 };
-import DmPlugin from '../../abstract/plugin';
 /**
  * Tell whether a mount prefix covers a request path, with the rule Express
  * itself applies: on segment boundaries, so `/api/m` covers `/api/m` and
@@ -18,18 +42,68 @@ import DmPlugin from '../../abstract/plugin';
  */
 export declare function prefixCoversPath(prefix: string, path: string): boolean;
 /**
- * Path prefixes claimed by scoped authentication plugins.
+ * Refuse a `--authz-identity` nobody wrote.
+ *
+ * Called by every plugin that keys on an identity, at construction. A value
+ * that is neither would otherwise mean `req.user` in silence, which is the
+ * wrong half of a security option to guess at.
+ *
+ * @param config the server configuration
+ * @param who the plugin asking, for the message
+ * @throws Error when the value is not one of the two
+ */
+export declare function assertIdentityMode(config: Config, who: string): void;
+/**
+ * The value an authorization rule is keyed on.
+ *
+ * `req.user` is this server's identifier for the caller and differs per
+ * authenticator — a token's name, an OIDC `sub`, a tenant — so a rule
+ * written for one is inert under another. `req.userName` is the same caller
+ * under a name a person would use, which is what makes a rule portable.
+ *
+ * When `req.userName` is asked for and missing, the answer falls back to
+ * `req.user` rather than to nothing: an authenticated caller read as
+ * anonymous would be *skipped* by the branch plugins, which is the one
+ * outcome a misconfiguration must not produce. The caller is told so it can
+ * say it once.
+ *
+ * @param req the request, or undefined
+ * @param config the server configuration
+ * @returns the identity to key on, and whether it is not the configured one
+ */
+export declare function identityFor(req: DmRequest | undefined, config: Config): {
+    value?: string;
+    fellBack: boolean;
+};
+/**
+ * What the loaded authenticators can name, and which of them cannot say.
  *
- * Takes the registry as an argument rather than reaching for the server, so
- * `DM` and `AuthBase` share one definition of what "claimed" means. The
- * registry is a live reference: it keeps filling as the remaining plugins
- * register, which is why the catch-all consults it per request.
+ * A rule is keyed on an identity, and a rule whose key no authenticator can
+ * produce matches nothing — it is not refused, it is *inert*, and that reads
+ * as a permission problem months later. Token, TOTP and HMAC names are in
+ * the configuration, so this is answerable at startup for them; an identity
+ * provider's claims are not, and saying "cannot verify" is the honest
+ * answer rather than silence.
  *
  * @param loadedPlugins the server's plugin registry
- * @param except name of the plugin asking, excluded from the result
- * @returns the prefixes other authentication plugins guard
+ * @returns the identities that can be named, and the plugins that cannot say
  */
-export declare function claimedPrefixes(loadedPlugins: Record<string, DmPlugin>, except?: string): string[];
+export declare function identityCoverage(loadedPlugins: Record<string, DmPlugin>): {
+    known: Set<string>;
+    unverifiable: string[];
+};
+/**
+ * Say, once at startup, when configured rules name nobody.
+ *
+ * @param keys the identities the rules are written for
+ * @param loadedPlugins the server's plugin registry
+ * @param who the plugin asking
+ * @param logger where to say it
+ */
+export declare function warnUnmatchedRuleKeys(keys: string[], loadedPlugins: Record<string, DmPlugin>, who: string, logger: {
+    warn: (message: string) => unknown;
+    info: (message: string) => unknown;
+}): void;
 export default abstract class AuthBase extends DmPlugin {
     abstract authMethod(req: DmRequest, res: Response, next: () => void): void;
     /** Validated prefixes, computed once: the catch-all reads them per request */
@@ -73,6 +147,98 @@ export default abstract class AuthBase extends DmPlugin {
      * @param next called only when the request is authenticated
      */
     authenticate(req: Request, res: Response, next: () => void): Promise<void>;
+    /**
+     * Publish the caller, under both names.
+     *
+     * Every authenticator calls this rather than assigning `req.user` itself,
+     * so that the second value cannot be forgotten by one of them — which is
+     * how a rule keyed on it would silently stop matching for that
+     * population.
+     *
+     * @param req request being authenticated
+     * @param user what authorization rules are keyed on, this plugin's own
+     *             identifier for the caller
+     * @param userName the caller under a name a person would use, when the
+     *                 plugin has one; the identifier otherwise
+     */
+    protected publishIdentity(req: DmRequest, user: string, userName?: string): void;
+    /**
+     * The identities this plugin can publish, when they are known before any
+     * request arrives.
+     *
+     * A configuration lists token, TOTP and HMAC names, so those plugins can
+     * answer; an identity provider's claims are only known once someone logs
+     * in, so those answer undefined and the check says so rather than
+     * guessing.
+     *
+     * @returns the identities, or undefined when they cannot be known
+     */
+    protected knownIdentities(): string[] | undefined;
+    /**
+     * Where the values this plugin publishes come from, for the startup line.
+     *
+     * Said once at startup because the mismatch it guards against — a rule
+     * written for one authenticator, inert under another — is invisible
+     * until a request arrives, and then reads as a permission problem.
+     *
+     * @returns a sentence naming both sources
+     */
+    protected identitySource(): string;
+    /**
+     * Say what this plugin will publish, once every plugin is loaded.
+     *
+     * A subclass overriding `afterLoad` for its own checks should call this
+     * one too.
+     */
+    afterLoad(): void;
+    /** Requests this plugin let through without authenticating them. */
+    private readonly passedThrough;
+    /**
+     * Let a request through without vouching for it.
+     *
+     * The dispatcher records every plugin that calls `next()` as having
+     * authenticated the request, and an authorization plugin scoped with
+     * `--authz-for` judges by that record. A plugin that steps aside — a
+     * bypass naming what *another* plugin authenticated, a verdict deferred to
+     * the end of the chain — has not, and must not appear there: a plugin
+     * scoped to it would judge requests whose identity it never produced.
+     *
+     * @param req the request passed on
+     * @param next continuation
+     */
+    protected passThrough(req: Request, next: () => void): void;
+    /**
+     * Whether this plugin authenticated the request it just let through.
+     *
+     * @param req a request this plugin called `next()` for
+     * @returns false when it only stepped aside
+     */
+    vouchedFor(req: Request): boolean;
+    /**
+     * A verdict this plugin could not reach while the chain was still running.
+     *
+     * The dispatcher calls it, on every selected plugin that implements it,
+     * once each of them has authenticated and before any route sees the
+     * request — the only moment where `req.user` is final and nothing has
+     * answered yet. A plugin needing it must not mount a middleware of its
+     * own: `api()` runs during registration, so such a middleware lands
+     * wherever that plugin fell among the others, and a route plugin
+     * registered first answers before it.
+     *
+     * `onAuth`/`afterAuth` are not that moment either: they run inside this
+     * plugin's own `authenticate`, while the authenticators after it have yet
+     * to run.
+     *
+     * Implement it only to answer a question that depends on what the *other*
+     * authenticators did — `core/auth/authzDynamic` uses it to apply a bypass
+     * written in terms of an identity another plugin publishes. Calling
+     * `next()` passes the request on; ending the response refuses it.
+     *
+     * @param req the authenticated request
+     * @param res response, ended by the plugin when it refuses
+     * @param next continuation, called when the plugin has nothing to say
+     */
+    afterChain?(req: DmRequest, res: Response, next: () => void): void;
     /**
      * Register with the server's authentication dispatcher instead of mounting
      * a middleware.

package/dist/src/lib/authz/base.d.ts

@@ -8,16 +8,42 @@
  */
 import type { SearchOptions } from 'ldapts';
 import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
 import type { BranchPermissions } from '../../config/args';
-import type { DmRequest } from '../auth/base';
-import type { AttributesList, ModifyRequest } from '../ldapActions';
+import { type DmRequest } from '../auth/base';
+import type { AttributesList, ModifyRequest, SearchResult } from '../ldapActions';
 /**
  * Abstract base class for authorization plugins
  * Provides common utility methods and interface for LDAP-based authorization
  */
 export default abstract class AuthzBase extends DmPlugin {
+    /**
+     * Searches whose projection we widened to carry the organization link.
+     *
+     * The filter cannot ask `opts` whether the caller wanted the attribute: by
+     * then `opts` is the widened one and would answer yes about an attribute
+     * we added ourselves. Holding the objects we touched keeps the question
+     * answerable, and a WeakSet lets them be collected with the request.
+     */
+    private static widenedForLink;
     roles: Role[];
     cacheTTL: number;
+    /** What `--authz-unresolved-user` accepts. */
+    private static readonly UNRESOLVED_POLICIES;
+    /**
+     * @param server DM object
+     */
+    constructor(server: DM);
+    /**
+     * Whether a search asked for this attribute.
+     *
+     * No projection at all means every user attribute, and so does `*`. `+`
+     * does not: it asks for the operational attributes, and the organization
+     * link is a user attribute — a search for `+` alone comes back without it,
+     * which is the very case the filter cannot judge, since an entry that
+     * arrived without its link looks attached to nothing.
+     */
+    protected static wantsAttribute(opts: SearchOptions | undefined, attr: string): boolean;
     /**
      * Extract the branch DN to check permissions against
      * For a DN like "uid=user,ou=users,ou=org,dc=example,dc=com"
@@ -26,6 +52,21 @@ export default abstract class AuthzBase extends DmPlugin {
      * Handles escaped commas in DN values (e.g., "cn=Smith\, John")
      */
     extractBranchDn(dn: string): string;
+    /**
+     * The branch a write is judged against.
+     *
+     * An account is stored in the same `ou=users` as everyone else, so its
+     * parent says nothing about who may touch it: what governs it is the
+     * organization it is attached to, which is read from the stored entry. An
+     * entry attached nowhere falls back to its parent, which is what an
+     * organization or a nomenclature value wants.
+     *
+     * Creation is not routed through here on purpose: `ldapaddrequest` reads
+     * the link off the entry being written and is not behind the flag, so
+     * unifying the two would judge an add on `ou=users` whenever the flag is
+     * off — a relaxation in the default configuration.
+     */
+    protected effectiveBranch(dn: string): Promise<string>;
     /**
      * Resolve user identifier to the format expected by getUserPermissions
      * This allows different implementations:
@@ -46,17 +87,105 @@ export default abstract class AuthzBase extends DmPlugin {
      */
     abstract getAuthorizedBranches(user: string): Promise<string[]>;
     /**
-     * Check if authorization should be skipped for this request
-     * Can be overridden by subclasses for custom logic
+     * Whether this request is none of this plugin's business.
+     *
+     * Two cases, and only two: a request with no identity (anonymous, skipped
+     * by design), and one that authentication plugins outside `--authz-for`
+     * vouched for — another population, judged by another model. An identity
+     * of *this* population that does not resolve is not skipped here: that is
+     * a configuration error, and `resolveCaller` refuses it. Inferring "not
+     * mine" from "cannot place it" is exactly the confusion this keeps apart.
+     *
+     * Subclasses overriding it must call this one.
      */
     protected shouldSkipAuthorization(req?: DmRequest): boolean;
+    /** What `resolveUser` answered for an identity, and when. */
+    private resolutionCache;
+    /** How many identities to remember at once. A cap, not a threshold. */
+    private static readonly RESOLUTION_CACHE_MAX;
+    /** Said once, when the cap is reached: a log line per request helps nobody. */
+    private resolutionCacheFullWarned;
+    /**
+     * Resolve the caller, or say what an identity that does not resolve means.
+     *
+     * `shouldSkipAuthorization` covers the request that carries no identity at
+     * all — anonymous, and skipped by design. This covers the other case: a
+     * request that *was* authenticated, whose identity this plugin's model
+     * cannot place.
+     *
+     * That used to return the operation untouched behind a `warn`, which made
+     * a configuration mismatch an open door rather than a refusal.
+     * `authzLinid1` resolves `req.user` by searching
+     * `(<ldap_user_main_attribute>=<identity>)`, so an authenticator
+     * publishing anything else — `core/auth/openidconnect` publishes the OIDC
+     * `sub`, `core/auth/llng` whatever `whatToTrace` traces — resolved to
+     * nothing on every request, and read, write and delete went through
+     * across the whole tree, with a line a `notice` production log does not
+     * show. (`authzPerBranch` fails the other way: the identity is its own key,
+     * so a mismatch yields all-false permissions and a refusal.)
+     *
+     * An authenticated identity that does not resolve is a failure of the
+     * configuration, not an absence of one, so it is refused.
+     * `--authz-unresolved-user allow` restores the old behaviour for a
+     * deployment that turns out to rely on it — a security fix should not
+     * rewrite every configuration by itself.
+     *
+     * Both answers are cached for `cacheTTL`, negatives included: a mismatch
+     * would otherwise turn every request into a directory search, so a
+     * configuration mistake would also become a load problem. The TTL cuts
+     * both ways, and neither way is free:
+     *
+     *  - an identity that appears in the directory after being refused waits
+     *    out the TTL before it is looked up again;
+     *  - a *positive* answer can go stale. `authzLinid1` resolves an identity
+     *    to a DN, so an administrator whose own entry is renamed or moved is
+     *    still resolved to the former DN, where no organization names them:
+     *    every operation is refused until the TTL runs out. A rename or a
+     *    delete therefore drops what was resolved, which closes the window
+     *    for the case that produces it; a change made directly in the
+     *    directory still waits.
+     *
+     * `authzScope` resolves the identity itself (`authzScope.ts`), outside
+     * this cache, so during such a window it can describe a scope the hooks
+     * no longer grant.
+     *
+     * @param req the request being authorized, which carries an identity
+     * @returns the resolved user, or null when the policy is to allow it
+     * @throws ForbiddenError when the policy is to deny it
+     */
+    /** Said once: a rule keyed on a value the authenticator did not publish. */
+    private fallbackWarned;
+    protected resolveCaller(req: DmRequest): Promise<string | null>;
+    /** Forget what was resolved, for a test that changes the directory. */
+    protected clearResolutionCache(): void;
     /**
      * Common hooks for all authorization plugins
      */
     hooks: {
+        /**
+         * A rename moves the entry an identity resolves to, so what was
+         * resolved is dropped.
+         *
+         * `authzLinid1` keys its permissions on the administrator's DN: renamed
+         * or moved, they resolve to a DN no organization names any more, and
+         * every operation of theirs is refused until the TTL runs out. The
+         * whole map goes rather than one key, since what is cached is
+         * identity → DN and the hook carries DNs: a handful of lookups is
+         * cheaper than working out which identity moved.
+         */
+        ldaprenamedone: () => void;
         ldapmodifyrequest: ([dn, changes, opNumber, req]: [string, ModifyRequest, number, DmRequest?]) => Promise<[string, ModifyRequest, number, DmRequest?]>;
         ldapaddrequest: ([dn, entry, req]: [string, AttributesList, DmRequest?]) => Promise<[string, AttributesList, DmRequest?]>;
         ldapsearchrequest: ([base, opts, req]: [string, SearchOptions, DmRequest?]) => Promise<[string, SearchOptions, DmRequest?]>;
+        /**
+         * Drop the accounts attached outside the branches this caller manages.
+         *
+         * Runs after the cache and carries the request, so what one caller may
+         * not see never reaches another. An entry with no organization link —
+         * an organization, a group, a nomenclature value — is left alone: those
+         * are the reference data every administrator reads.
+         */
+        ldapsearchfilter: ([result, req, opts]: [SearchResult, DmRequest?, SearchOptions?]) => Promise<[SearchResult, DmRequest?, SearchOptions?]>;
         getOrganisationTop: ([req, defaultTop]: [DmRequest | undefined, AttributesList | null]) => Promise<[DmRequest | undefined, AttributesList | null]>;
         ldaprenamerequest: ([oldDn, newDn, req]: [string, string, DmRequest?]) => Promise<[string, string, DmRequest?]>;
         ldapdeleterequest: ([dn, req]: [string | string[], DmRequest?]) => Promise<[string | string[], DmRequest?]>;

package/dist/src/lib/authz/composition.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @module lib/authz/composition
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * How authorization plugins loaded together compose, and the configurations
+ * where that composition is nobody's decision.
+ *
+ * Every plugin judging LDAP operations registers the same hooks, and
+ * `launchHooksChained` runs them all: two of them compose as an AND, the
+ * first refusal winning. That is a sound rule when it is meant. It is a
+ * refusal nobody can explain when it is not — `authzPerBranch` beside
+ * `authzDynamic` judges a machine token by a branch configuration written
+ * for administrators, finds no key for the tenant, and refuses a write the
+ * token's own ACLs grant. So a plugin says whose requests it judges
+ * (`--authz-for`), and the server refuses to start when two of them judge
+ * the same ones without `--authz-combine`.
+ * @group Libraries
+ */
+import type DmPlugin from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Config } from '../../config/args';
+import type { DmRequest } from '../auth/base';
+/**
+ * The hooks an LDAP operation is judged in: refused from, or — for
+ * `ldapsearchfilter` — narrowed to what the caller may see. Two plugins on
+ * the last one compose as an intersection, which is the same AND.
+ */
+export declare const LDAP_JUDGING_HOOKS: readonly ["ldapsearchrequest", "ldapaddrequest", "ldapmodifyrequest", "ldapdeleterequest", "ldaprenamerequest", "ldapsearchfilter"];
+/** Every authenticated request, whatever authenticated it. */
+export declare const EVERYONE = "everyone";
+/** The requests a plugin judges: named authenticators', or everyone's. */
+export type Population = string[] | typeof EVERYONE;
+/** An authentication plugin, as far as composition is concerned. */
+interface Authenticator {
+    name: string;
+    pathPrefixes: string[];
+}
+/**
+ * The authentication plugins an authorization plugin judges the requests of.
+ *
+ * @param config the plugin's configuration
+ * @param who the plugin, for the message
+ * @returns their instance names, or undefined for every one of them
+ * @throws Error when the option is not a list of names
+ */
+export declare function authzFor(config: Config, who: string): string[] | undefined;
+/**
+ * Whether a plugin configured with `config` judges this request.
+ *
+ * A request no authenticator vouched for — the list absent, or empty while
+ * something set `req.user` anyway — is judged: skipping is only for a
+ * request that *someone else's* authenticator vouched for, and inferring
+ * that from an absence would turn a gap into an open door.
+ *
+ * @param req the request, or undefined for an operation outside one
+ * @param config the plugin's configuration
+ * @returns false only when every authenticator that vouched is another's
+ */
+export declare function servesRequest(req: DmRequest | undefined, config: Config): boolean;
+/**
+ * Whether two authenticators can both vouch for one request.
+ *
+ * The dispatcher runs the plugins claiming the longest matching prefix, all
+ * of them, so two plugins run together exactly when they claim the same
+ * prefix — or when neither claims any, on the paths nobody else does. A
+ * prefix nested in another's is not shared: the longer one wins on its
+ * paths, and the shorter one alone runs on the rest.
+ *
+ * @param a an authenticator
+ * @param b another one
+ * @returns true when a request can carry both stamps
+ */
+export declare function runTogether(a: Authenticator, b: Authenticator): boolean;
+/** A plugin that judges LDAP operations, and whose. */
+export interface Judge {
+    plugin: DmPlugin;
+    hooks: string[];
+    population: Population;
+}
+/**
+ * The plugins judging LDAP operations.
+ *
+ * A plugin that authenticates as well — `authzDynamic` — judges its own
+ * requests and no others: its hooks read the token it verified, and a request
+ * without one passes them untouched. The others judge the population
+ * `--authz-for` gives them, everyone by default.
+ *
+ * @param server the server, once every plugin is loaded
+ * @returns one entry per judging plugin, in registration order
+ */
+export declare function ldapJudges(server: DM): Judge[];
+/**
+ * Whether two populations can share a request, and how.
+ *
+ * @param a a population
+ * @param b another one
+ * @param authenticators the loaded authentication plugins
+ * @returns `same` when one authenticator is in both, `together` when a
+ *          request can be vouched for by one of each, undefined otherwise
+ */
+export declare function overlap(a: Population, b: Population, authenticators: Authenticator[]): 'same' | 'together' | undefined;
+/**
+ * Say a population in words, for the log.
+ *
+ * `everyone` names the authenticators it takes in: the accident this module
+ * is about is a branch model judging an authenticator nobody wrote it for,
+ * and a line saying "every request" would not show it.
+ *
+ * @param population the population
+ * @param authenticators the loaded authentication plugins
+ * @returns a phrase
+ */
+export declare function describePopulation(population: Population, authenticators: Authenticator[]): string;
+/**
+ * Refuse the compositions nobody decided, and say the others.
+ *
+ * - an `authz_for` naming no loaded authentication plugin is refused: the
+ *   plugin would judge nobody, which reads as a working configuration;
+ * - an `authz_for` of its own on a plugin that authenticates is said: it
+ *   judges the requests it vouched for, and the option is inert there;
+ * - two plugins judging the LDAP operations of the same authenticator's
+ *   requests are refused unless `--authz-combine` makes the AND deliberate;
+ * - two judging authenticators that run on the same prefix — a request
+ *   carrying both credentials is judged by both — are said, not refused:
+ *   asking for two credentials is already a decision;
+ * - every judge is named with the hooks it takes part in and whose requests
+ *   it judges.
+ *
+ * `authzPerRoute` gates URLs and registers no LDAP hook, so it is never part
+ * of the AND this refuses: route plus branch is a documented combination,
+ * and each side judges identities it can name.
+ *
+ * Run once every plugin of the configuration is loaded, over all of them;
+ * and for a plugin registered after that — a server assembled by hand —
+ * over what that one plugin adds, before it is registered. What it adds is
+ * judged against what is already there, so an authorization plugin naming
+ * authenticators is registered after them.
+ *
+ * @param server the server
+ * @param candidate a plugin about to be registered, present in
+ *        `server.loadedPlugins`; only what concerns it is checked
+ * @throws Error naming the plugins when the composition is ambiguous
+ */
+export declare function assertAuthzComposition(server: DM, candidate?: DmPlugin): void;
+export {};

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

@@ -4,8 +4,15 @@
  */
 import type { Request, Response } from 'express';
 import type winston from 'winston';
-export declare const setLogger: (logger: winston.Logger) => void;
-export declare const getLogger: () => winston.Logger;
+/**
+ * Install the logger, or remove it: a test restores the state it found,
+ * which before any `DM` is none.
+ *
+ * @param logger the logger, or undefined for none
+ */
+export declare const setLogger: (logger: winston.Logger | undefined) => void;
+/** @returns the installed logger, or undefined before any `DM` exists */
+export declare const getLogger: () => winston.Logger | undefined;
 export declare const tryMethod: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
 export declare const tryMethodData: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
 export declare const ok: (res: Response, data?: object) => void;

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

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;