ldap-rest 1.2.1 → 2.0.0

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

@@ -0,0 +1,226 @@
+/**
+ * The hooks of the server, typed by `Hooks`, with one calling convention per
+ * kind.
+ *
+ * The three kinds are told apart by what their subscriber answers:
+ * chained hooks get a value and pass it — possibly changed — along the
+ * chain; notified hooks answer nothing, are not waited for, and their
+ * failures are logged; several hooks answer a value each.
+ *
+ * @see docs/plugin-development/hooks.md
+ */
+import type { Hooks } from '../hooks';
+export type HookFn = Function;
+/** A promise, or the value itself */
+type Settled<T> = T extends Promise<infer P> ? P : T;
+/** Whether `F` answers nothing: `void`, or a promise of it */
+export type AnswersVoid<F> = [
+    Settled<F extends (...args: never[]) => infer R ? R : never>
+] extends [void | undefined] ? true : false;
+/** The values of `Hooks` a chain threads: the ones whose answer is a value */
+export type ChainedName = {
+    [K in keyof Hooks]-?: AnswersVoid<NonNullable<Hooks[K]>> extends true ? never : K;
+}[keyof Hooks];
+/** The `Hooks` a notification fires: the ones whose subscriber answers nothing */
+export type NotifiedName = Exclude<keyof Hooks, ChainedName>;
+/** A chained hook is declared with the value it threads */
+export type ChainedNameOf<K extends keyof Hooks> = K extends ChainedName ? K : never;
+/** The arguments a hook expects */
+export type Args<K extends keyof Hooks> = NonNullable<Hooks[K]> extends (...args: infer A) => unknown ? A : never;
+/** What a chained hook threads */
+export type ChainedValue<K extends keyof Hooks> = NonNullable<Hooks[K]> extends (arg: infer A) => unknown ? A : never;
+/**
+ * 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: HookFn, 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: HookFn) => {
+    plugin: string;
+    hook: string;
+} | undefined;
+/**
+ * Run a hook under its plugin's name and its own, for the lines it logs.
+ *
+ * @param hook the registered function
+ * @param fn its run
+ * @returns what `fn` returns
+ */
+export declare const runAsHookOwner: <T>(hook: HookFn, fn: () => T) => T;
+/**
+ * A hook's list, as `server.hooks` spells it: `undefined` when nothing is
+ * subscribed, a function for one subscriber, a list for several, and
+ * anything else when a test writes a list through the hook and walks it.
+ */
+export type HookValue<K extends keyof Hooks = keyof Hooks> = Hooks[K] | Function[] | undefined;
+/** The functions a subscriber value holds, one or many */
+export declare const asHooks: <K extends keyof Hooks>(value: HookValue<K>) => HookFn[];
+/**
+ * How a flat entity raises its own hooks, see `abstract/ldapFlat.ts`: the
+ * prefix it names them under, added to the suffix of each. They are not
+ * `Hooks`' own, see {@link FlatHookPrefix}.
+ */
+export interface FlatHookBus {
+    /** Thread a value through `{prefix}{suffix}`, as {@link HookBus.chain} */
+    chain<T>(suffix: string, value: T): Promise<T>;
+    /** Notify `{prefix}{suffix}`, as {@link HookBus.notify} */
+    notify(suffix: string, ...args: unknown[]): void;
+}
+export default class HookBus implements FlatHookBus {
+    /**
+     * What `server.hooks` holds, shared by reference. A plugin reaching it
+     * directly is not told by its type whether the hook exists, nor how it
+     * is called; this bus is.
+     */
+    private readonly hooks;
+    private readonly tracked;
+    /**
+     * @param hooks the server's hook lists, shared by reference
+     */
+    constructor(hooks: {
+        [K in keyof Hooks]?: HookValue<K>;
+    });
+    /** Whether anything is subscribed to a hook */
+    has(name: keyof Hooks): boolean;
+    /**
+     * The subscribers of a hook, in the order they run.
+     *
+     * @param name the hook
+     * @returns its subscribers, empty when nothing subscribed
+     */
+    subscribers(name: keyof Hooks): readonly HookFn[];
+    /**
+     * Subscribe a function to a hook, or forget its subscribers when given
+     * none, as a plugin declaring `hooks` would.
+     *
+     * @param name the hook
+     * @param fn what to run, none to unsubscribe every subscriber
+     */
+    set<K extends keyof Hooks>(name: K, ...fn: NonNullable<Hooks[K]>[]): void;
+    /**
+     * Add a subscriber to a hook, after the ones already there.
+     *
+     * @param name the hook
+     * @param fn what to run
+     */
+    subscribe<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>): void;
+    /**
+     * Put a subscriber at a given place in a hook's list, as
+     * `registerPlugin` does for an authorization hook.
+     *
+     * @param name the hook
+     * @param fn what to run
+     * @param at its place, the end when past it
+     */
+    insert<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>, at: number): void;
+    /**
+     * Remove a subscriber from a hook, wherever it sits.
+     *
+     * @param name the hook
+     * @param fn the subscriber
+     */
+    unsubscribe<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>): void;
+    /**
+     * Move a subscriber to the end of its hook's list, keeping it registered,
+     * for a plugin that must run after every other one.
+     *
+     * @param name the hook
+     * @param hook the subscriber
+     * @returns whether it was subscribed to the hook
+     */
+    toLast(name: keyof Hooks, hook: HookFn): boolean;
+    /**
+     * Thread a value through every subscriber of a chained hook, each getting
+     * what the one before answered. The first failure stops the chain and
+     * travels up: a refusal is a refusal, and the caller must not go on as if
+     * the chain had said yes.
+     *
+     * Hooks run outside the request being served: what a hook reads or writes
+     * to validate, complete or keep track of an operation is the server's
+     * (#385). The request is in the arguments of the hooks that judge, which
+     * judge by it; a hook acting as the caller names it.
+     *
+     * @param name the hook
+     * @param value the value to thread
+     * @returns the last value in the chain
+     */
+    chain<K extends keyof Hooks>(name: ChainedNameOf<K>, value: ChainedValue<K>): Promise<ChainedValue<K>>;
+    /**
+     * Notify every subscriber of a hook, one after the other, outside the
+     * request that caused it: they are told what happened, and was judged, and
+     * react as the server — synchronizing, publishing, keeping invariants —
+     * whoever asked.
+     *
+     * Not awaited, and not failed: the write the subscribers react to is done,
+     * and a subscriber's failure is logged and goes no further. `settled`
+     * waits for them.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     */
+    notify<K extends NotifiedName>(name: K, ...args: Args<K>): void;
+    /**
+     * Run every subscriber of a hook and let their failures go to the caller,
+     * for the rare hook whose subscribers are part of the answer: a logout
+     * token reaches the provider only once what it closes is recorded, so the
+     * failure has to reach the library, which answers 400 and lets the
+     * provider retry.
+     *
+     * Every subscriber runs even when one fails, one after the other as
+     * `notify` runs them, and the first failure is raised once they all have:
+     * stopping at the first would cost the others their turn — a session the
+     * provider considers closed would keep working against the store that
+     * would have killed it.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     */
+    notifyStrict<K extends NotifiedName>(name: K, ...args: Args<K>): Promise<void>;
+    /**
+     * Notify, then wait for the subscribers: a caller that has to know the
+     * consequences have run, a test instead of a sleep.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     * @returns once they have returned
+     */
+    notifyAndWait<K extends NotifiedName>(name: K, ...args: Args<K>): Promise<void>;
+    /**
+     * Run every hook the server holds and answer what each gives, in order.
+     * For the hooks nothing decided the answer of: `hello` is a demo of one.
+     *
+     * @param name the hook
+     * @param args what its subscribers are given
+     * @returns one answer per subscriber
+     */
+    call<K extends keyof Hooks>(name: K, ...args: Args<K>): Promise<unknown[]>;
+    /**
+     * A view raising `{prefix}{suffix}` hooks, for an entity whose hooks are
+     * named dynamically.
+     *
+     * @param prefix the entity's prefix
+     * @returns the bus, raising its hooks
+     */
+    prefixed(prefix: string): FlatHookBus;
+    /**
+     * Resolves when every notification started so far has run, the ones
+     * started while waiting included.
+     */
+    settled(): Promise<void>;
+    /**
+     * Write a hook's subscribers the way `server.hooks` spells them: no entry
+     * when nothing is subscribed, the function itself for one subscriber.
+     */
+    private store;
+    private fire;
+}
+export {};

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

@@ -1,11 +1,3 @@
-/**
- * @module lib/instanceProviders
- *
- * The two places a workplace instance can be created: the Cloudery, which
- * answers at once and builds the instance afterwards, and the cozy-stack
- * admin API, which builds it before answering.
- */
-import { type RequestInit, type Response } from 'node-fetch';
 /**
  * Reduce a name to what the Cloudery takes in a slug; it refused `_` or `@`
  * with "Slug is invalid". `-` is kept, except at either end where no host

package/dist/src/lib/ldap/callerView.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The directory as one caller sees it: whether a route may tell them an
+ * entry exists, and what the `ldapsearchfilter` hooks leave of a result.
+ */
+import type { Request } from 'express';
+import type { SearchOptions, SearchResult } from 'ldapts';
+export interface CallerViewOptions {
+    /** Run a search for the caller who asks. */
+    search: (options: SearchOptions, base: string, req?: Request) => Promise<SearchResult | AsyncGenerator<SearchResult>>;
+    /** Whether any plugin filters search results. */
+    hasFilter: () => boolean;
+    /** Hand one chunk to `ldapsearchfilter`. */
+    filter: (chunk: SearchResult, req?: Request, opts?: SearchOptions) => Promise<SearchResult>;
+}
+export default class CallerView {
+    private readonly search;
+    private readonly hasFilter;
+    private readonly filterHook;
+    constructor(options: CallerViewOptions);
+    /**
+     * 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>;
+    /**
+     * 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.
+     */
+    filter(value: SearchResult | AsyncGenerator<SearchResult>, req?: Request, opts?: SearchOptions): SearchResult | AsyncGenerator<SearchResult> | Promise<SearchResult>;
+}

package/dist/src/lib/ldap/pool.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The directory connections this server keeps: failover between the URLs,
+ * a bounded pool with a TTL, and the readiness probe on a connection of its
+ * own.
+ */
+import { Client } from 'ldapts';
+import type { ClientOptions } from 'ldapts';
+export interface PoolLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export interface PooledConnection {
+    client: Client;
+    createdAt: number;
+    inUse: boolean;
+}
+/** Opens a client; binding is the pool's, so a fake can stand in. */
+export type ClientFactory = (options: ClientOptions) => Client | Promise<Client>;
+export interface LdapPoolOptions {
+    /** The URLs to try. */
+    urls: string[];
+    dn: string;
+    pwd: string;
+    /** Options shared by every URL; the pool sets `url` and `tlsOptions`. */
+    options: ClientOptions;
+    poolSize: number;
+    connectionTtl: number;
+    logger: PoolLogger;
+    clientFactory?: ClientFactory;
+}
+export default class LdapPool {
+    private readonly urls;
+    private readonly dn;
+    private readonly pwd;
+    private readonly options;
+    private readonly poolSize;
+    private readonly connectionTtl;
+    private readonly logger;
+    private readonly clientFactory;
+    private connectionPool;
+    private availableConnections;
+    private waitingResolvers;
+    /** Connections being opened, not yet in `connectionPool` */
+    private opening;
+    private isCleaningUp;
+    private currentUrlIndex;
+    /** Set by `close`: no connection is handed out any more */
+    private closed;
+    constructor(options: LdapPoolOptions);
+    /**
+     * Create a new LDAP connection with failover support
+     */
+    private createConnection;
+    /**
+     * Clean up expired connections from the pool
+     * Uses a flag to prevent concurrent cleanup operations
+     */
+    private cleanupExpiredConnections;
+    /**
+     * Ask the directory for its root DSE on a connection of its own, bound
+     * as the server and closed after: the readiness probe. Neither the pool
+     * nor the search cache nor the hooks answer for a directory that does
+     * not, and a directory that stops answering holds nothing of the pool.
+     * The URLs are tried as `createConnection` tries them.
+     *
+     * @param timeoutMs how long the connection, the bind and the search may
+     *   each take; the client closes the socket when it passes
+     * @throws when no URL answers in time
+     */
+    ping(timeoutMs: number): Promise<void>;
+    /**
+     * Close every pooled connection, the ones in use included: an operation
+     * still running on one is rejected by the client, and a waiter is refused
+     * rather than kept.
+     */
+    close(): Promise<void>;
+    /**
+     * Acquire a connection from the pool or create a new one
+     * Optimized for O(1) lookup using separate available connections queue
+     */
+    acquire(): Promise<PooledConnection>;
+    /**
+     * Run `operation` on a pooled connection, released whatever becomes of it.
+     */
+    withConnection<T>(operation: (client: Client) => Promise<T>): Promise<T>;
+    /** Throw when `close` ran: the pool hands out no connection any more. */
+    assertOpen(): void;
+    /** The pool as it is, for the metrics */
+    stats(): {
+        busy: number;
+        idle: number;
+        waiting: number;
+        opening: number;
+        max: number;
+    };
+    private takeConnection;
+    /** Refuse every queued request with `error` */
+    private refuseWaiters;
+    /** Let one queued request take a place that freed with no connection */
+    private wakeWaiter;
+    /**
+     * Release a connection back to the pool
+     * If there are waiting requests, hand off the connection directly
+     */
+    release(pooled: PooledConnection): void;
+}

package/dist/src/lib/ldap/schema.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The directory schema: where it lives, its index, how this server spells
+ * attribute names, the object classes an entity declares and the repair a
+ * write needs.
+ */
+import type { SearchOptions, SearchResult } from 'ldapts';
+import type { AttributesList, ModifyRequest } from '../ldapActions';
+import { SchemaIndex } from '../ldapSchema';
+export interface SchemaLogger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+export type DirectorySearch = (options: SearchOptions, base: string) => Promise<SearchResult | AsyncGenerator<SearchResult>>;
+export interface DirectorySchemaOptions {
+    logger: SchemaLogger;
+    /** Run a search as the server itself. */
+    search: DirectorySearch;
+    /** Whether a modify may add the classes it needs. */
+    autoRepair: () => boolean;
+    /** How long the schema index is kept, in milliseconds. */
+    schemaCacheTtl: () => number;
+}
+export default class DirectorySchema {
+    private readonly logger;
+    private readonly search;
+    private readonly autoRepair;
+    private readonly schemaCacheTtl;
+    /** See {@link declareObjectClasses}. */
+    private declaredClasses;
+    private schemaCache?;
+    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(options: DirectorySchemaOptions);
+    /**
+     * Declare the object classes an entity gives the entries of its branch.
+     *
+     * An entry created by another tool may lack some of them, and a class it
+     * lacks can forbid an attribute written here: the organization link of an
+     * account made as a bare `inetOrgPerson` is refused by the directory. A
+     * modify writing such an attribute adds the auxiliary class that allows
+     * it, see {@link classRepair}.
+     *
+     * @param base branch holding the entity's entries
+     * @param classes object classes the entity's schema declares; a schema
+     * file may give a single one as a string
+     * @param includeBase whether the base is itself one of the entries, as the
+     * top organization is
+     */
+    declareObjectClasses(base: string, classes: string[] | string, includeBase?: boolean): void;
+    /**
+     * The classes declared for the branch holding a DN. Several entities may
+     * share a branch — the shipped `users`, `posixAccounts` and
+     * `sshPublicKeys` schemas all live in `ou=users` — so every declaration at
+     * the deepest matching base counts.
+     */
+    private declaredFor;
+    /**
+     * Log a class problem of an entry once, not on every write to it: nothing
+     * an administrator can do stops a sync job from touching it again.
+     */
+    private warnOnce;
+    /**
+     * The auxiliary classes a modify needs added: for each attribute it writes
+     * that the entry's classes do not allow, a class declared for its branch
+     * or by the writer that allows it, provided the entry holds or receives
+     * that class's mandatory attributes once the change is applied.
+     *
+     * Only what the write needs is added. Entities sharing a branch declare
+     * classes that are not all meant for every entry: `shadowAccount` is not
+     * something every account should be given because it sits in `ou=users`.
+     * And a write that the directory would have accepted is never changed.
+     *
+     * Nothing is added when the change names `objectClass` itself, and a
+     * schema or entry that cannot be read skips the repair.
+     *
+     * @param dn entry being modified
+     * @param changes the modification, after the hooks
+     * @param extra classes the writer declares, see {@link ModifyOptions}
+     * @returns names of the classes to add, or `allowed` when the entry's
+     * classes take the change as it is
+     */
+    classRepair(dn: string, changes: ModifyRequest, extra?: string[]): Promise<string[] | 'allowed'>;
+    /**
+     * DN of the subschema entry the root DSE advertises, or the conventional
+     * `cn=Subschema` when it advertises none.
+     */
+    subschemaDn(): Promise<string>;
+    /**
+     * The directory schema, kept for `--ldap-raw-schema-cache-ttl`: it is
+     * large and changes rarely. The raw browser and the object class repair
+     * share it, and concurrent callers share a single read.
+     *
+     * @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. So is, with or without
+     * it, a name that is neither a descriptor nor a numeric OID.
+     *
+     * @param entry attributes of an add, or one part of a modify
+     * @throws BadRequestError on an option, on a name that describes no
+     * attribute, 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;
+}

package/dist/src/lib/ldap/searchCache.d.ts

@@ -0,0 +1,112 @@
+import type { SearchOptions, SearchResult } from 'ldapts';
+export interface CacheLogger {
+    info(message: string): void;
+}
+export interface SearchCacheOptions {
+    max: number;
+    /** Milliseconds; 0 switches the cache off. */
+    ttl: number;
+    logger: CacheLogger;
+}
+/**
+ * Short, stable stand-in for a cache key in a log line.
+ *
+ * The key is built from the search base, which comes from configuration and
+ * therefore ultimately from the environment — logging it verbatim is what
+ * CodeQL flags as clear-text logging of environment-derived data. A digest
+ * carries none of the key's content, but the same key always digests to the
+ * same token, so a "cache hit" line can still be matched back to the
+ * "cached" line that filled the entry it hit.
+ */
+export declare const digestKey: (key: string) => string;
+/** The DNs that attributes of an entry or a change name as members. */
+export declare const membersNamed: (attributes: Record<string, unknown> | undefined) => string[];
+/** The parts of a change that name members, as `applyModify` reads them. */
+type MembershipChanges = {
+    add?: Record<string, unknown>;
+    replace?: Record<string, unknown>;
+    delete?: string[] | Record<string, unknown>;
+};
+export default class SearchCache {
+    readonly enabled: boolean;
+    private readonly logger;
+    private readonly searchCache;
+    /**
+     * How many writes this cache has seen.
+     *
+     * A read can be overtaken by a write: the write lands and `invalidate`
+     * finds nothing to drop, because the read has not stored its answer yet —
+     * and the read then stores what it read *before* the write, an entry
+     * nothing will drop until its TTL runs out. A search remembers the count
+     * it started at and stores only if no write happened in between, so a read
+     * a write overtook costs a cache entry, never a stale answer.
+     *
+     * The count is per cache and per write, not per DN: a write to another
+     * branch keeps a concurrent read out of the cache too. That is hit rate
+     * given up, not freshness.
+     */
+    private cacheGeneration;
+    constructor(options: SearchCacheOptions);
+    get generation(): number;
+    /**
+     * Generate cache key for LDAP search
+     *
+     * Every option that changes the answer belongs in here, or a search that
+     * asked for more is served what a search that asked for less got: the
+     * requested attributes above all, but also the ones that change the shape
+     * of what comes back. `timeLimit` is deliberately absent — it bounds how
+     * long the server may spend, not what it returns.
+     */
+    key(base: string, opts: SearchOptions): string;
+    /** The cached answer, as a copy the caller may edit. */
+    get(key: string): SearchResult | undefined;
+    /** Store a copy of the answer; later callers cannot edit what was stored. */
+    set(key: string, result: SearchResult): void;
+    /**
+     * Drop every cached read of `dn`, and of everything below it.
+     *
+     * Called after each write, so the next read of what just changed goes to
+     * the directory. It compares DNs the way the directory does (see
+     * {@link foldDn}), so a write spelling a DN differently from the read that
+     * cached it still drops it; and it drops the subtree, because a rename or
+     * a move re-parents a whole branch in one operation — renaming an
+     * organization changes the DN of every entry under it — leaving the cached
+     * reads of those children filed under DNs that no longer exist. A leaf has
+     * nothing below it and the extra test costs nothing.
+     */
+    invalidate(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 invalidate} 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.
+     */
+    invalidateReferences(dn: string): void;
+    /**
+     * Drop what a change of a group's members makes stale: the group, what
+     * names it, and the members the change names. A replace or a delete of
+     * every value removes members the change no longer names; their cached
+     * reads are found by the group's DN in their `memberOf`.
+     */
+    invalidateMembership(dn: string, changes: MembershipChanges): void;
+    /**
+     * Get a sorted signature for an attribute list.
+     *
+     * The signature is JSON, not a separator-joined string: an attribute
+     * description may contain any character that could stand for a separator,
+     * so joining would let `['cn|mail']` and `['cn', 'mail']` share one.
+     */
+    private getAttributeSignature;
+}
+export {};