ldap-rest 1.3.0 → 2.0.1

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,22 @@ 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
 
+### [Architecture](architecture/README.md)
+
+How the server is put together.
+
+- **[Overview](architecture/README.md)** - Module map, life of a request, life of a write
+- **[Decision records](architecture/adr/)** - Why the code is the way it is
+
+### [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.
+- **[Modularization plan](development/modularization-plan.md)** - How the
+  `@ldap-rest/*` split and the remaining code-quality issues are sequenced.
+
 ## API stability
 
 From 1.0.0, ldap-rest follows semantic versioning. These are its public
@@ -44,8 +61,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 +76,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/architecture/README.md

@@ -0,0 +1,180 @@
+# Architecture
+
+How the server is put together, and the two paths that carry most of the
+work. Every design decision the code already embodies is recorded once, in
+[`adr/`](adr/); this page is the map and the tour.
+
+The plan that will split the repository into packages is
+[Modularization plan](../development/modularization-plan.md). That plan is a
+roadmap; this page describes the code as it is.
+
+## Module map
+
+| Path                   | Role                                                                                                                                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/bin/index.ts`     | `DM`: the Express app, plugin loading, the authentication dispatcher, `ready` and `stop`, `withConfig`                                                                                |
+| `src/config/`          | Command-line and environment parsing (`args.ts`), option specs (`options.ts`), the entity-schema model (`schema.ts`; the directory's own schema is `src/lib/ldap/schema.ts`)          |
+| `src/abstract/`        | `DmPlugin` base class; `LdapFlat`, the entity CRUD built on it; `TwakePlugin`                                                                                                         |
+| `src/hooks.ts`         | The hook type map: one entry per hook, with its arguments and its answer                                                                                                              |
+| `src/lib/`             | Core services: `ldapActions` and `lib/ldap/` (pool, search cache, schema), `lib/auth/`, `lib/authz/`, `lib/services/`, `lib/storage/`, `hookBus`, `requestContext`, errors, routes    |
+| `src/plugins/auth/`    | Authentication plugins, authorization plugins, and the guards that sit before them                                                                                                    |
+| `src/plugins/ldap/`    | Directory plugins: groups, organizations, entities, change detection, trash, password policy                                                                                          |
+| `src/plugins/scim/`    | The SCIM 2.0 API                                                                                                                                                                      |
+| `src/plugins/storage/` | Storage backends (`file`, `ldap`, `postgres`, `valkey`), each a `Store`                                                                                                               |
+| `src/plugins/twake/`   | Twake integrations: mail, calendar, spaces, drives, tombstones, lifecycle events                                                                                                      |
+| `src/plugins/*.ts`     | Standalone plugins: `storage` (`core/storage`, over the backends above), `static`, `weblogs`, `configApi`, `metrics`, `bcl`, and `rabbitmq` (a shared broker connection, not a store) |
+| `src/plugins/demo/`    | Example plugins                                                                                                                                                                       |
+| `src/browser/`         | Browser libraries shipped with the package                                                                                                                                            |
+| `src/logger/`          | Log formatting and levels                                                                                                                                                             |
+| `src/types/`           | Shared TypeScript declarations                                                                                                                                                        |
+
+The plugin families depend on `src/lib/` and on each other as documented in
+[dependencies](../plugin-development/dependencies.md). The dependency rules
+that the modularization will enforce are in the
+[plan](../development/modularization-plan.md#target-architecture).
+
+## Life of a request
+
+```mermaid
+flowchart TD
+    A[HTTP request] --> B[request id and log context]
+    B --> C[body parsers]
+    C --> D[protect plugins: rate limit, CrowdSec, trusted proxy]
+    D --> E[authentication dispatcher]
+    E --> F{most specific prefix}
+    F -->|one authenticator| G[vouched]
+    F -->|several on the same prefix| H[all of them, an AND]
+    H --> G
+    G --> I[runForRequest]
+    I --> J[route: checked params, query, body]
+    J --> K[ldap.forRequest or ldap.system]
+    K --> L[request hooks, authorization first]
+    L --> M[(directory)]
+    M --> N[done hooks of a write, then end hooks]
+    N --> O[onLdap* notifications]
+    J --> P[error middleware]
+```
+
+1. `DM` mounts, in this order: the request id and log context
+   (`runWithLogContext`), the media-type guard, the parsers a plugin
+   registered for its own prefix, the global JSON and form parsers (they keep
+   the raw bytes: HMAC authentication hashes them as the client signed them),
+   the health probes, the protect and logging plugins, the authentication
+   dispatcher, the plugin routes, and the error middleware, kept last.
+2. The dispatcher picks the authentication whose path prefix is the most
+   specific. Several plugins sharing that winning prefix all run, in
+   registration order, and every one must let the request through: two
+   credentials on one branch are an AND. A path nobody claims is guarded by
+   the unscoped authenticators (no prefix), if any are loaded; with none, the
+   request passes through unauthenticated, and `warnUnauthenticatedRoutes`
+   names those routes at startup.
+3. A plugin's `afterChain` runs after the whole selected chain and before any
+   route: it is the only place where a verdict can depend on several
+   authenticators without registration order deciding the answer.
+4. `runForRequest(req, next)` wraps everything downstream of a request an
+   authenticator let through — not the pass-through path, which has no
+   caller. A directory operation made there, by whatever plugin, is judged as
+   that caller even if the request object was not handed down. Hooks are the
+   exception: they run as the server (see below), and a hook acting as the
+   caller names the request it received. `ldap.system` is the explicit escape
+   anywhere else.
+5. A route declares its input schemas with `defineRoute`; the handler receives
+   checked `params`, `query` and `body`, and reaches the directory through
+   `ldap.forRequest(req)`. Work the server does for itself goes through
+   `ldap.system`.
+6. `ldapActions` raises the request hooks (authorization plugins first), makes
+   the operation, then raises the "done" and "end" hooks of a write. The next
+   section follows one.
+
+The decisions behind these steps: [authentication
+dispatch](adr/0002-authentication-dispatch.md), [authorization
+composition](adr/0003-authorization-composition.md), [fail-closed request
+context](adr/0004-fail-closed-request-context.md).
+
+## Life of a write
+
+```mermaid
+sequenceDiagram
+    participant R as route
+    participant L as ldapActions
+    participant H as plugins
+    participant D as directory
+
+    R->>L: add / modify / rename / delete
+    L->>H: request hook, chained (authorization first)
+    H-->>L: value, changed or refused
+    L->>L: drop cached reads the write changes
+    L->>D: LDAP add / modify / modifyDN / delete
+    D-->>L: result
+    L->>L: drop them again
+    L->>H: done hooks, notified
+    L->>H: end hooks, once the done hooks returned
+    H->>H: onLdapEntryChange, onLdapChange, onLdapMailChange…
+```
+
+- **Before the write.** A request hook is chained: each subscriber gets what
+  the previous one answered, and a refusal thrown by any of them stops the
+  operation. The request hooks of authorization plugins run before every
+  other subscriber's, so a caller who may not make the operation is refused
+  before a plugin judges its content.
+  [trash](adr/0007-trash-and-tombstone.md) and
+  [tombstone](adr/0007-trash-and-tombstone.md) use this point to replace a
+  delete.
+- **The write.** `ldapActions` drops the cached reads of what it is about to
+  change before the directory call and again once it returned, so a read
+  landing during the round trip cannot serve what the write replaced.
+  [Search cache](adr/0006-search-cache.md).
+- **After the write.** `ldapadddone`, `ldapmodifydone`, `ldapdeletedone` and
+  `ldaprenamedone` are notified, not awaited. `ldapaddafter` is awaited
+  within the request, for what must follow an add, such as provisioning the
+  account the entry describes. Once the done subscribers returned, the
+  matching `ldapmodifyend`, `ldapdeleteend` or `ldaprenameend` fires, whether
+  the write landed, was refused or was taken out of the request.
+- **Derived notifications.** `core/ldap/onChange` reads the entry before and
+  after the write and raises `onLdapEntryChange`, then the attribute-specific
+  ones (`onLdapMailChange`, `onLdapQuotaChange`, …). A delete fires
+  `onLdapEntryChange`, `onLdapChange` and `onLdapMailChange` only.
+- **Contract.** [Hook contract](adr/0005-hook-contract.md), and the reference
+  of every hook in [hooks](../plugin-development/hooks.md). Subscribers run as
+  the server, outside the request that raised the hook; one that acts as the
+  caller names the request in its arguments.
+
+## Startup
+
+The configuration is parsed from the command line and `DM_*` variables, then
+`DM` loads the plugins: `src/plugins/priority.json` first, one at a time in
+its order, then the rest in parallel. Once every load settled, the server
+checks the authorization composition, learns the directory's attribute types
+when an authorization plugin is loaded, reports unknown options and runs
+`afterLoad`. `DM.ready` resolves then, and rejects if a plugin failed to load;
+the CLI opens the port after it. An embedding host may register plugins after
+`ready`, and each registration is checked against the composition too.
+`warnUnauthenticatedRoutes` stays silent when no authentication plugin is
+loaded; the enforcement check says once whether that is an open server or a
+configuration to refuse.
+
+[Plugin load order](adr/0001-plugin-load-order.md),
+[server views](adr/0008-withconfig-views.md).
+
+## Decision records
+
+| Record                                          | Decision                                                                                |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [0001](adr/0001-plugin-load-order.md)           | Plugins load priority-first, then in parallel; dependencies load on demand              |
+| [0002](adr/0002-authentication-dispatch.md)     | The most specific authentication prefix wins; several on one prefix are an AND          |
+| [0003](adr/0003-authorization-composition.md)   | Two authorization models judging the same requests are refused unless made deliberate   |
+| [0004](adr/0004-fail-closed-request-context.md) | Directory operations inherit the request being served; `ldap.system` is the escape      |
+| [0005](adr/0005-hook-contract.md)               | Chained hooks transform and refuse; notified hooks observe, outside the request         |
+| [0006](adr/0006-search-cache.md)                | The search cache is off by default and only the process's own writes invalidate it      |
+| [0007](adr/0007-trash-and-tombstone.md)         | A delete becomes a move to trash or a tombstone, never a loss                           |
+| [0008](adr/0008-withconfig-views.md)            | A plugin with overrides sees a server view that shares everything but the configuration |
+
+## Checking the comments
+
+`npm run check:comments` (`scripts/check-comments.sh`) refuses new comments in
+`src/` that cite an issue number, narrate history ("used to", "since 1.2") or
+otherwise carry rationale. The rationale belongs in a decision record; the
+comment points at it. The accepted set is `scripts/comment-baseline.txt`, and
+it may only shrink: removing a comment is fine, adding one fails the check.
+`sh scripts/check-comments.sh --update` rewrites the baseline from the current
+tree when a change removes one.

package/docs/architecture/adr/0001-plugin-load-order.md

@@ -0,0 +1,50 @@
+# 0001 — Plugin load order
+
+## Context
+
+Plugins are listed with `--plugin`, in the order the administrator writes
+them, and a plugin may declare `dependencies` naming modules that must be
+registered before it. Some plugins cannot simply be imported in parallel with
+the rest: a guard whose Express middleware must sit ahead of the routes it
+protects, an access log that must see every request, an authenticator or URL
+gate other plugins must find registered when they register. Import order in
+the parallel batch is the order the imports happen to complete, which is not a
+configuration.
+
+## Decision
+
+`src/plugins/priority.json` lists the modules loaded first. That pass is
+sequential, in the file's order, and every instance of a priority module is
+loaded there, in configuration order — matching is on the module, not on the
+whole `--plugin` entry, so a named instance (`module:name:{…}`) keeps its
+rank. The remaining entries load in parallel. A declared dependency is loaded
+on demand when the plugin that needs it registers. A module requested twice
+under the same name without overrides is loaded once; a second instance needs
+its own name. Two plugins with the same instance name are refused, and the
+second is dropped with a warning. `configApi` loads last.
+
+The list holds four kinds of plugin: the guards whose middleware must run
+before the routes (`trustedProxy`, `crowdsec`, `rateLimit`), the access log
+that must see every request (`weblogs`), the authenticators the dispatcher and
+the authorization plugins naming them have to find registered (`token`,
+`fake`, `llng`, `openidconnect`), and the URL gate whose rules must exist
+before the routes they judge (`authzPerRoute`). `core/storage` is there
+because others must find it registered when they register.
+
+Hooks run in load order, except the request hooks of authorization plugins,
+which run before every other subscriber's.
+
+## Consequences
+
+- A plugin whose middleware must precede routes has to be in
+  `priority.json`; being written first in the configuration is not enough
+  once the parallel batch starts.
+- The relative order of two plugins that are neither priority nor linked by a
+  dependency is not defined, and no plugin may rely on it.
+- Adding a module to the priority list changes the order for every
+  deployment, so the list stays short.
+- An instance named with overrides loads at the rank of its module but keeps
+  its own configuration through a [server view](0008-withconfig-views.md).
+
+See [dependencies](../../plugin-development/dependencies.md) and
+`src/bin/index.ts`.