ldap-rest 1.3.0 → 2.0.0

package/dist/src/lib/services/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed services between plugins: a token names the interface a consumer
+ * reads and the instance a provider offers, so the compiler checks both.
+ *
+ * @see docs/plugin-development/services.md
+ */
+declare const serviceType: unique symbol;
+/**
+ * What identifies a service: a name for the logs, and the interface it
+ * answers. The type is carried by a phantom property and never exists at
+ * runtime; the object itself is the registry key.
+ */
+export interface ServiceToken<T> {
+    /** Names the service in the logs */
+    readonly name: string;
+    /** Type only, never set: carries the interface a consumer reads */
+    readonly [serviceType]?: T;
+    /**
+     * Bind the instance providing this service, as a plugin's `provides`
+     * declares. The argument must answer the interface the token names.
+     *
+     * @param provider the plugin instance providing the service
+     * @returns the token and its provider
+     */
+    with(provider: T): ServiceProvider<T>;
+}
+/** A token with the instance providing it, as a plugin declares them. */
+export interface ServiceProvider<T> {
+    readonly token: ServiceToken<T>;
+    readonly service: T;
+}
+/**
+ * Declare a service.
+ *
+ * Declare a token once, in a module both the provider and its consumers
+ * import: the object is the registry key, and a second declaration under the
+ * same name would be another service. The name only identifies it in the
+ * logs.
+ *
+ * @param name the service name
+ * @returns the token, carrying its interface
+ */
+export declare const serviceToken: <T>(name: string) => ServiceToken<T>;
+/** What `DM.services` holds: the provided instance for each token. */
+export type ServiceMap = Map<ServiceToken<unknown>, unknown>;
+/**
+ * The instance provided for a token, when a plugin provides it.
+ *
+ * A provider always answers something: `undefined` means nobody provides it.
+ *
+ * @param services the server's registry
+ * @param token the service wanted
+ * @returns the provided instance, or undefined
+ */
+export declare const providedService: <T>(services: ReadonlyMap<ServiceToken<unknown>, unknown>, token: ServiceToken<T>) => T | undefined;
+export {};

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

@@ -155,6 +155,30 @@ export declare function parseDn(dn: string): string[];
  * @returns whether it reads as a DN
  */
 export declare function isDnSyntax(dn: string): boolean;
+/**
+ * Whether every escape in `dn` is one RFC 4514 §3 defines: an escaped
+ * special (`" + , ; < > \ # =` or a space) or a pair of hex digits.
+ *
+ * {@link parseDn} and {@link unescapeDnValue} read a DN permissively, as a
+ * directory may answer one; a DN a caller writes is held to the grammar.
+ *
+ * @param dn - The DN to check
+ * @returns whether its escapes are RFC 4514 escapes
+ */
+export declare function hasOnlyRfc4514Escapes(dn: string): boolean;
+/**
+ * Refuse a DN a client wrote when it holds an escape RFC 4514 does not
+ * define.
+ *
+ * The readers here are permissive on purpose, because they also read what a
+ * directory answers. A DN a caller sends is held to the grammar instead, so
+ * the server only ever writes a spelling the directory would produce itself.
+ *
+ * @param dn - The DN the client wrote
+ * @param what - What to name in the refusal
+ * @throws BadRequestError when an escape is not one RFC 4514 defines
+ */
+export declare function assertRfc4514Escapes(dn: string, what: string): void;
 /**
  * Extract the parent DN from a DN
  * Removes the first RDN component to get the parent branch
@@ -206,9 +230,11 @@ export declare function rdnValue(dn: string): string;
  * Read the name of an entry written as a DN: the value of its first RDN when
  * that RDN asserts `attribute` alone, under `base` when one is given.
  *
- * The value is decoded exactly as {@link rdnValue} decodes it: it is the
- * naming attribute's value, the one a write puts back in
- * `attribute=…,base`.
+ * The value is decoded as {@link rdnValue} decodes it, then folded as the
+ * directory folds it ({@link foldRdnValue}): it is the naming attribute's
+ * value, the one a write puts back in `attribute=…,base`, and a caller
+ * spelling it in a way the directory considers the same name gets that name,
+ * not a second one.
  *
  * @param dn - The DN to read
  * @param attribute - The attribute the first RDN must assert
@@ -249,6 +275,26 @@ export declare function namesByDn(id: string, attribute: string): boolean;
  * ```
  */
 export declare function isChildOf(dn: string, parentDn: string): boolean;
+/**
+ * Whether `dn` names a direct child of `base`: its parent is `base`, compared
+ * as the directory compares DNs.
+ *
+ * `isChildOf` answers ancestry; this answers parent equality, which is what a
+ * route that only serves one branch requires of a DN a client writes. The
+ * comparison folds case, spacing and the escapes the directory reads, so a
+ * DN created under one spelling is addressed under another.
+ *
+ * @param dn - The DN to check
+ * @param base - The branch its parent has to be
+ * @returns True when the DN has a parent and that parent is `base`
+ *
+ * @example
+ * ```typescript
+ * isDirectChildOf('uid=x,OU=Users , dc=example,dc=com', 'ou=users,dc=example,dc=com')
+ * // => true
+ * ```
+ */
+export declare function isDirectChildOf(dn: string, base: string): boolean;
 /**
  * Teach {@link normalizeDn} the names and OIDs of attribute types: each is
  * read as the type's first name.
@@ -299,6 +345,15 @@ export declare function rdnTypes(dn: string): string[];
  * ```
  */
 export declare function normalizeDn(dn: string): string;
+/**
+ * A DN's structure normalized as {@link normalizeDn} does, with the case of
+ * its values kept.
+ *
+ * A configured expression compiled to ignore case reads a DN through this
+ * form: its values are folded as the directory folds them, but a value it
+ * captures keeps the spelling the caller wrote.
+ */
+export declare function canonicalDn(dn: string): string;
 /**
  * Whether a member DN is the placeholder a `groupOfNames` holds so it stays
  * valid with no real member (`--group-dummy-user`).
@@ -374,6 +429,20 @@ export declare function isDnInBranch(dn: string, base: string): boolean;
  * @returns true when the entry entered the trash branch
  */
 export declare function movedToTrash(trashBase: string | undefined, oldDn: string, newDn: string): boolean;
+/**
+ * Parse a directory date: an LDAP generalized time or anything `Date`
+ * understands.
+ *
+ * A generalized time (RFC 4517 section 3.3.13) is `yyyyMMddHH`, then optional
+ * minutes and seconds, an optional fraction of the last unit given, and a zone:
+ * `Z` or an offset of hours with optional minutes (`+02`, `-0530`). `Date` reads
+ * none of the shorter forms, and not an offset of bare hours, so they are
+ * computed here rather than rewritten into an ISO string it might refuse.
+ *
+ * @param raw value as stored or submitted
+ * @returns the date, or null when it cannot be read
+ */
+export declare function parseDirectoryDate(raw: AttributeValue): Date | null;
 /**
  * Wrapper for async Express route handlers to catch errors and pass them to error middleware
  * This ensures that errors in async routes are properly handled and don't crash the server

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

@@ -107,20 +107,6 @@ export declare function parseByteSize(raw: AttributeValue): number;
  * @returns true when the rules supply a value
  */
 export declare function fillsGeneratedAttribute(name: string, attr: SchemaAttribute, schema: Schema): boolean;
-/**
- * Parse a directory date: an LDAP generalized time or anything `Date`
- * understands.
- *
- * A generalized time (RFC 4517 section 3.3.13) is `yyyyMMddHH`, then optional
- * minutes and seconds, an optional fraction of the last unit given, and a zone:
- * `Z` or an offset of hours with optional minutes (`+02`, `-0530`). `Date` reads
- * none of the shorter forms, and not an offset of bare hours, so they are
- * computed here rather than rewritten into an ISO string it might refuse.
- *
- * @param raw value as stored or submitted
- * @returns the date, or null when it cannot be read
- */
-export declare function parseDirectoryDate(raw: AttributeValue): Date | null;
 /**
  * Start of a day, in UTC.
  *

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

@@ -353,9 +353,10 @@ export default class PasswordPolicy extends DmPlugin {
     private deletePolicy;
     private assignPolicy;
     /**
-     * Parse GeneralizedTime (YYYYMMDDHHmmssZ) to Date
+     * A time the directory wrote, or null when the entry holds none, read as
+     * the rest of LDAP-Rest reads one: see {@link parseDirectoryDate}.
      */
-    private parseGeneralizedTime;
+    private parsePolicyTime;
     /**
      * Validate password complexity (optional local validation)
      */

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

@@ -27,9 +27,11 @@ export declare function withExternalId(mapping: ResourceMapping, ldapAttribute:
  * `xsd:dateTime` and reject anything else, so the raw directory value must not
  * be forwarded as-is.
  *
- * A value that does not look like a GeneralizedTime is returned untouched: a
- * directory may already store an ISO 8601 string, and dropping it would lose
- * more than passing it through.
+ * The instant is read by {@link parseDirectoryDate}, as every other directory
+ * time is; this only writes it in the form SCIM asks for, in UTC. A value that
+ * does not look like a GeneralizedTime is returned untouched: a directory may
+ * already store an ISO 8601 string, and dropping it would lose more than
+ * passing it through.
  */
 export declare function ldapTimeToIso(value: string | undefined): string | undefined;
 export declare function loadMappingFile(path: string): ResourceMapping | undefined;
@@ -163,6 +165,17 @@ export declare function scimGroupToLdap(group: ScimGroup, mapping: ResourceMappi
  * mapped SCIM attributes can be populated.
  */
 export declare function requiredLdapAttributes(mapping: ResourceMapping, extra?: string[]): string[];
+/**
+ * Refuse a DN a client wrote in a mapped reference when it holds an escape
+ * RFC 4514 does not define.
+ *
+ * The mapping says which sub-attributes carry a DN (`subDn`): a reference
+ * such as `manager.value` is written to the directory as sent, where the
+ * entity validator that holds the flat routes to RFC 4514 never sees it.
+ */
+export declare function assertReferenceDn(value: string, what: string): void;
+/** Whether the mapping declares this sub-attribute a DN (`subDn`). */
+export declare function isDnSubAttribute(mapping: ResourceMapping, top: string, sub: string): boolean;
 /**
  * Given a SCIM attribute path like "emails.value" or "name.familyName",
  * return the corresponding LDAP attribute name (used by filter parser).

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

@@ -147,6 +147,8 @@ export interface MappingEntry {
     ldapPrimary?: string;
     ldapSecondary?: string;
     sub?: Record<string, string>;
+    /** Sub-attributes whose value is a DN, held to RFC 4514 on write */
+    subDn?: string[];
     multi?: 'single' | 'array';
     readOnly?: boolean;
     operational?: boolean;

package/dist/src/plugins/twake/instances.d.ts

@@ -12,6 +12,8 @@ export interface WorkplaceCreated {
 /** An account's instance request, and the id `user.created` names it by. */
 interface Account extends InstanceRequest {
     twakeId: string;
+    /** The organization id came from the DN, not from the provider settings */
+    fromDn?: boolean;
 }
 export declare const EnsureInstanceBody: import("@sinclair/typebox").TObject<{
     dn: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -128,12 +130,41 @@ export default class TwakeInstances extends DmPlugin {
     private get organizationFqdn();
     private organizationMail;
     private isOrganization;
+    /**
+     * The id the organization's own entry spells, for an id captured from a
+     * client's DN: the caller may write the branch in another case, and the
+     * Cloudery branch and the slug should not follow it. The captured value
+     * stands when there is no entry or no organization base.
+     */
+    private storedOrganizationId;
+    /** `account()`, with a captured organization id read from its entry. */
+    private storedAccount;
     private findOrganization;
     private read;
     protected announce(exchange: string, key: string, message: Record<string, unknown>): Promise<void>;
     /** What to ask for this account, when it gets an instance at all. */
     protected account(dn: string, entry: AttributesList): Account | undefined;
+    /**
+     * The expression that takes this DN for an account's, and where it sits.
+     *
+     * Each expression reads the canonical DN first: a client may spell the
+     * branch differently, and a space or an escape inside a captured value
+     * would otherwise be captured as written. The canonical form keeps the
+     * caller's case, which an organization id is sent as. An expression written
+     * with the directory's own spelling — `\2C`, a doubled space — does not
+     * match that form, so the DN as sent is tried next.
+     */
     private match;
+    /**
+     * The DN with a comma inside a value written `\2C`, as the directory writes
+     * it: an expression's `[^,]` cannot then read that comma as an RDN
+     * separator and name the branch of an entry beside it.
+     */
+    private separators;
+    /** The uid of an account's DN, under any name or alias of the type. */
+    private uid;
+    /** One queue per entry, whatever spelling its DN came in. */
+    private key;
     private id;
     protected value(entry: AttributesList, attribute: string): unknown;
     protected findByMail(email: string, req?: Request): Promise<AttributesList | undefined>;

package/dist/src/plugins/twake/lifecycleAttributes.d.ts

@@ -25,5 +25,16 @@ export declare function first(value: AttributeValue | null | undefined): string
 export declare const isTombstone: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
 export declare const isLocked: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
 export declare function formatDeletedAt(date: Date, format: DeletedAtFormat): string;
-/** A deletion date as the directory holds it, or undefined if unreadable. */
-export declare function parseDeletedAt(value: string, format: DeletedAtFormat): Date | undefined;
+/**
+ * A deletion date as the directory holds it, or undefined if unreadable.
+ *
+ * Read by the same reader as every other directory time: the format only says
+ * how this deployment writes the date, not how it is read.
+ *
+ * A value of another shape is refused here rather than handed to that
+ * reader, whose fallback to `new Date()` reads `1` or `Jan 1` as a date: the
+ * erase guard takes an unreadable date for a refusal. The same fallback rolls
+ * `2025-02-31` over to March, where the shared reader refuses that day
+ * spelled as a GeneralizedTime.
+ */
+export declare function parseDeletedAt(value: string): Date | undefined;

package/dist/src/plugins/twake/tombstone.d.ts

@@ -48,8 +48,8 @@ export default class TwakeTombstone extends DmPlugin {
      */
     tombstone(dn: string, reason: string, req?: Request): Promise<void>;
     /**
-     * Remove a tombstone and its group memberships. Refused while the deletion
-     * is younger than the configured age, unless forced.
+     * Remove a tombstone and its group memberships. Refused when its deletion
+     * date is unreadable or younger than the configured age, unless forced.
      */
     erase(dn: string, { force, req }?: {
         force?: boolean;
@@ -77,6 +77,13 @@ export default class TwakeTombstone extends DmPlugin {
      * group the erase left holding only the placeholder loses it again.
      */
     private restore;
+    /**
+     * Whether this DN names an entry the expressions keep. A client may spell
+     * the DN differently from the expression; the directory stores the entry
+     * at its canonical DN, so the expressions read that too. The DN as sent is
+     * still tried: an expression written with the directory's own spelling
+     * (`\2C`, a doubled space) matches only that form.
+     */
     private matches;
     private isScim;
     private checkReason;

package/docs/README.md

@@ -20,6 +20,7 @@ Create and extend LDAP-Rest with custom plugins.
 
 - **[Development Guide](plugin-development/README.md)** - Architecture and plugin creation
 - **[Hooks](plugin-development/hooks.md)** - LDAP hooks system
+- **[Services](plugin-development/services.md)** - Typed interfaces between plugins
 - **[Routes](plugin-development/routes.md)** - Declaring routes and their input schemas
 - **[Testing](plugin-development/testing.md)** - Testing with embedded LDAP
 - **[Dependencies](plugin-development/dependencies.md)** - Plugin dependencies matrix
@@ -33,6 +34,13 @@ Integrate LDAP-Rest into your web applications.
 - **[JSON Schemas](client-development/schemas/README.md)** - Schema structure and validation
 - **[Examples](client-development/examples/README.md)** - React, Vue.js, Vanilla JS integration
 
+### [Development](development/contracts.md)
+
+Work on ldap-rest itself.
+
+- **[Published contracts](development/contracts.md)** - What breaks a
+  contract, the snapshots that detect it and the deprecation window.
+
 ## API stability
 
 From 1.0.0, ldap-rest follows semantic versioning. These are its public
@@ -44,8 +52,9 @@ API, which a minor or a patch release does not break:
   [REST API](client-development/api/rest-api.md) and the plugin pages,
   their statuses and their error `code`s.
 - **Plugin API**: what `ldap-rest/plugin` exports — `DmPlugin` and its
-  roles (`auth`, `authz`, …), `asyncHandler`, the DN and filter escaping
-  helpers and the error classes —, the `DM` type of `ldap-rest` and the
+  roles (`auth`, `authz`, …), `serviceToken`, `ServiceToken` and
+  `ServiceProvider`, `asyncHandler`, the DN and filter escaping helpers and
+  the error classes —, the `DM` type of `ldap-rest` and the
   `Hooks` of `ldap-rest/hooks`, whose arguments are those typed in
   `src/hooks.ts` ([hooks](plugin-development/hooks.md)), and the directory
   operations of [the development guide](plugin-development/README.md):
@@ -58,6 +67,11 @@ API, which a minor or a patch release does not break:
 Everything else — other exports, internal helpers, log messages — may
 change in any release.
 
+The options and the REST API are checked mechanically: committed snapshots
+are compared with the base branch of each pull request, and a non-additive
+change needs the `breaking` label. The plugin types are still reviewed by
+hand. See [Published contracts](development/contracts.md).
+
 ## Presentations
 
 Interactive presentations (using [presenterm](https://github.com/mfontanini/presenterm)):

package/docs/client-development/api/rest-api.md

@@ -1365,6 +1365,10 @@ const encoded = encodeURIComponent(dn);
 // Result: uid%3Djohn.doe%2Cou%3Dusers%2Cdc%3Dexample%2Cdc%3Dcom
 ```
 
+A path parameter is percent-decoded once, as RFC 3986 spells it: an
+identifier holding `%` is sent as `%25`, so `100%` is addressed as
+`/api/v1/ldap/users/100%25`.
+
 ### LDAP Attributes are Arrays
 
 LDAP attributes are always returned as arrays, even for single-valued attributes:

package/docs/development/contracts.md

@@ -0,0 +1,109 @@
+# Published contracts
+
+Other code depends on three things ldap-rest publishes. A change to one that
+is not additive breaks that code, so it needs a major release and the pull
+request says so before it merges.
+
+- **Configuration**: the CLI options and `DM_*` variables of
+  [Configuration](../usage/configuration.md) and of each plugin's page.
+- **REST API**: the routes, request bodies and answers of the
+  [REST API](../client-development/api/rest-api.md), their parameters,
+  responses (references resolved), statuses and response headers. The error
+  `code` values are reviewed by hand: the document types them as strings.
+- **Plugin API**: what the npm sub-path exports declare — `ldap-rest`,
+  `./hooks`, `./plugin`, `./ldapactions`, `./expressformatedresponses`, the
+  `./plugin-*`, `./abstract-*` and `./browser-*` entries — and the JSON
+  schema format of the `./schema-*` entries.
+
+[API stability](../README.md#api-stability) says what a minor or patch
+release promises. This page says how a change is detected, and what to do
+when it is not additive.
+
+## Committed snapshots
+
+Two snapshots are generated locally and checked in CI, so a change to a
+contract shows up as a diff instead of a surprise after the release:
+
+- `docs/usage/options.snapshot.json` lists every option's CLI name, plural
+  form, environment variable, type, default, kind, required flag and aliases.
+  Regenerate it with `npm run snapshot:options`; `npm run check:options`, part
+  of `npm run check`, fails when it is stale.
+- `openapi.json` is the REST API document the published reference is built
+  from. Regenerate it with `npm run generate:openapi`; `npm run check:openapi`
+  fails when it is stale.
+
+The plugin types have no snapshot yet: one api-extractor report per sub-path
+export is a change of its own. Until it lands, a change to an exported type is
+reviewed by hand.
+
+The snapshot records what the parser reads. A narrowed `choices` list, a
+raised `min` or a lowered `max` is checked when a plugin reads its options,
+not by the snapshot, and is reviewed by hand, as is a custom error `code`.
+
+## The pull request gate
+
+The `contracts` job of `.github/workflows/contracts.yml` generates the
+snapshots from the pull request and compares them with the base branch's
+committed ones. It reports:
+
+- additive changes — a new option, route or field — and lets them through;
+- non-additive changes, and fails unless the pull request carries the
+  `breaking` label.
+
+A change is non-additive when it removes or narrows what was published:
+a removed option or environment variable, a changed type, default, bound,
+`const`, enum or required flag, a request value that becomes an enum, a
+request object that stops accepting additional properties, a removed route,
+method, parameter, response status, response header or field, a request field
+that becomes required, a response that may now be null, changed security
+requirements, a removed union variant, a value an alternative of the type
+closes with an enum or a `const` where the type used to accept any, an
+untyped request value that becomes a union, an `allOf` that adds a
+constraint, or — once the plugin snapshot exists — a removed export or a
+narrowed signature. Renaming an option is a deprecation, not a removal, as
+long as the old CLI name and environment variable stay in its `aliases` and
+`envAliases`. Adding a union variant, a field or an optional parameter is
+additive, and so is a request union with an alternative that still accepts
+everything the base did — in a response the client reads every alternative,
+so a field the others drop is still a removal. A `oneOf` is the exception:
+it refuses a value two alternatives match, so an alternative as wide as the
+base narrows the others away, and the alternatives are not told apart from
+one another — a disjoint `oneOf` therefore asks for the label too.
+Documentation-only edits, such as a summary or description, are ignored.
+
+The job runs the scripts from the pull request, so a change to them is
+reviewed like any other code, as `.github/CODEOWNERS` requires.
+
+The `breaking` label records that the maintainers accepted the break, and the
+`CHANGELOG.md` section must say so: the release gate below reads the section,
+not the label, and refuses to ship the break as a minor or patch release. The
+workflow listens to label events, so adding the label runs the job again; it
+has its own concurrency group, so that event does not cancel the test matrix.
+
+To try the comparison locally against your base branch:
+
+```bash
+npx tsx scripts/contracts.ts --base origin/master
+```
+
+## The release gate
+
+`.github/workflows/release.yml` runs `scripts/check-release.ts` on the tag. A
+non-major tag whose `CHANGELOG.md` section lists `### Breaking Changes` is
+refused. For a 0.x version, a minor release counts as major, as semantic
+versioning lets it break. When the tag has no section of its own, the gate
+reads `## Unreleased`, so a tag cut before the section was renamed is still
+checked; with neither section it fails. When the CHANGELOG lists no earlier
+release, only a first `X.0.0` counts as major, so a trimmed file cannot open
+the gate.
+
+## Deprecating instead of breaking
+
+The window and the rules are in
+[CONTRIBUTING.md](../../CONTRIBUTING.md#deprecating-a-published-contract).
+The mechanics of an option alias are in
+[plugin options](../plugin-development/options.md#deprecating-an-option): the
+old CLI name and environment variable go in `aliases` and `envAliases`, and
+the server warns at startup while it still reads them. An array option's
+plural form has no alias slot: renaming it is a breaking change, so it waits
+for a major release.

package/docs/plugin-development/README.md

@@ -7,6 +7,7 @@ This guide will help you create powerful, production-ready plugins for LDAP-Rest
 - [Why Create a Plugin](#why-create-a-plugin)
 - [Plugin Structure](#plugin-structure)
 - [Creating Your Plugin](#creating-your-plugin)
+- [Plugin services](./services.md)
 - [Custom Configuration Options](#custom-configuration-options)
   - [Plugin options](./options.md)
 - [Loading Your Plugin](#loading-your-plugin)
@@ -54,6 +55,8 @@ export default class MyPlugin extends DmPlugin {
 - **roles** (optional): Array categorizing plugin purpose
 - **dependencies** (optional): Required plugins that must load first
 - **hooks** (optional): Callbacks for LDAP operations
+- **provides** (optional): Typed services this plugin offers, see
+  [plugin services](services.md)
 - **api()** (optional): Method to register REST endpoints
 
 ### Available from Base Class
@@ -65,6 +68,8 @@ export default class MyPlugin extends DmPlugin {
 - **this.logger**: Winston logger instance
 - **this.hookBus**: The server's hooks: chain, notify and wait on them, see
   [hooks](hooks.md#the-bus)
+- **this.service(token)**: The instance another plugin provides under a
+  service token, or `null`, see [plugin services](services.md)
 - **this.fetch**: `fetch` timed into the
   [outbound metrics](../usage/operations.md#metrics) under the plugin's
   name; the lint refuses a bare `fetch` or `node-fetch` under `src`, and a
@@ -452,7 +457,8 @@ const results = await this.server.ldap.search(
   'ou=users,dc=example,dc=com'
 );
 
-// Search with pagination (returns AsyncGenerator)
+// Search with pagination (returns AsyncGenerator; the connection is taken
+// when the first page is read)
 const pagedResults = await this.server.ldap.search(
   {
     paged: true,
@@ -1320,6 +1326,7 @@ See [Tests and checks](../../CONTRIBUTING.md#tests-and-checks).
 
 - [Contributing Guide](../../CONTRIBUTING.md) - Git workflow and PR guidelines
 - [Hooks Reference](./hooks.md) - Complete list of available hooks
+- [Plugin services](./services.md) - Typed interfaces between plugins
 - [Core Plugin Examples](../../src/plugins/) - Browse existing plugins
 - [Test Examples](../../test/plugins/) - See how core plugins are tested
 

package/docs/plugin-development/dependencies.md

@@ -1,9 +1,10 @@
 # Plugin Dependency Graph
 
-This document describes the dependencies between LDAP-Rest plugins. There are two types of dependencies:
+This document describes the dependencies between LDAP-Rest plugins. There are three types of dependencies:
 
 1. **Explicit Dependencies**: Defined in the `dependencies` property of a plugin class
-2. **Hook Dependencies**: Implicit dependencies through hooks (one plugin provides a hook, another consumes it)
+2. **Service Dependencies**: A plugin reaches a typed interface another one provides, see [plugin services](services.md)
+3. **Hook Dependencies**: Implicit dependencies through hooks (one plugin provides a hook, another consumes it)
 
 ## Dependency Types
 
@@ -24,6 +25,16 @@ overrides — a dependency also given to `--plugin`, or an entry listed twice
 is loaded once: the second request waits for the first. Only an entry with
 overrides builds a second instance, and it needs a name of its own.
 
+### Service Dependencies
+
+A plugin provides a typed interface under a token, and a consumer reaches it
+with `this.service(token)`. The token replaces the registry name as the way to
+find another plugin's code; `dependencies` still decides what loads first. A
+consumer whose provider is absent gets `null` and a single warning.
+
+See [plugin services](services.md) for the token, the provided interface and
+the registration rules.
+
 ### Hook Dependencies
 
 **Hook Providers**: Plugins that implement hooks (via `hooks: Hooks = { ... }`)

package/docs/plugin-development/hooks.md

@@ -60,7 +60,7 @@ await server.hookBus.settled();
 - **hello**: raised by the [demo plugin](../../src/plugins/demo/helloworld.ts) for `/hello`, answered by the demo plugins
 - **ldapsearchopts**: chained before any search, with its options
 - **ldapsearchrequest**: chained before any search, with `[base, options, request]`; an authorization plugin refuses by throwing
-- **ldapsearchresult**: chained after any search, with its result, before it is cached
+- **ldapsearchresult**: chained after any search, with its result, before it is cached; for a paged search, when the first page is read
 - **ldapsearchfilter**: chained on the result of a search after the cache, once per page, with `[result, request, options]`, to drop what the caller may not see
 - **ldapaddrequest**: chained before any add, with `[dn, entry, request]`
 - **ldapadddone**: notified once an add has written the entry, with the DN, the entry and the context, one by one; not awaited
@@ -118,6 +118,7 @@ await server.hookBus.settled();
 - **scimgroupdeletedone**: notified once a SCIM group is deleted, with its id
 - **scimbulkdone**: notified once a SCIM bulk request is answered
 - **twakedeletionreplay**: notified with the DN, the entry and the context, one by one when a delete asks of an entry that is already a tombstone
+
 <!-- /hooks -->
 
 ## Flat entities