ldap-rest 1.3.0 → 2.0.1

package/docs/development/modularization-plan.md

@@ -0,0 +1,197 @@
+# Modularization plan
+
+How the remaining architecture work is sequenced: [#397] and the five
+`code-quality` issues that depend on it or prepare it. The plan is a roadmap,
+not a contract; update it as the work lands.
+
+## Open issues
+
+| Issue  | Subject                                                                             | Role                          | Size   |
+| ------ | ----------------------------------------------------------------------------------- | ----------------------------- | ------ |
+| [#397] | Split the repository into `@ldap-rest/*` modules                                    | Final step                    | Major  |
+| [#593] | Finish the plugin service migration: entity registry, call sites, family boundaries | Prerequisite of #397          | Large  |
+| [#594] | Finish the `ldapActions` split: operation pipeline and façade                       | Prerequisite of #397          | Medium |
+| [#595] | Snapshot the plugin API types and gate changes                                      | Safety net, start before #397 | Medium |
+| [#549] | Architecture pages, decision records, comment check                                 | Independent, start early      | Medium |
+| [#603] | Enable the type-checked ESLint rules the test block leaves out                      | Independent, quick win        | Small  |
+
+[#397] is still in the `2.0.0` milestone, which is released. Retarget it to a
+2.x epic or to 3.0.0 once the compatibility decision below is made. [#593] and
+[#594] are labelled `Minor`/`backlog` but are the real prerequisites of
+[#397]; promote them to the same milestone.
+
+## What blocks #397 today
+
+The core still imports plugin code:
+
+- `src/config/args.ts` imports the option sets of every plugin family.
+- `src/bin/index.ts` imports `src/plugins/priority.json`.
+- `src/hooks.ts` imports `ChangesToNotify` from
+  `src/plugins/ldap/onChange.ts` and the SCIM types from
+  `src/plugins/scim/types.ts`.
+- `src/abstract/ldapFlat.ts` reads `server.loadedPlugins` and uses
+  `requirePlugin`.
+- `src/lib/ldapActions.ts` is 1,375 lines; `src/lib/ldap/operations.ts` does
+  not exist.
+- The single package generates 66 `./plugin-*` exports from
+  `rollup.config.mjs`, with no npm workspaces.
+
+Between plugin families the coupling is smaller: only the Twake plugins import
+`ldap`/`scim` (15 imports), plus `TwakeGroups extends LdapGroups`.
+
+## Target architecture
+
+An npm workspaces monorepo with an umbrella package that preserves the public
+API:
+
+```text
+packages/
+  core/                 @ldap-rest/core
+  plugin-auth/          @ldap-rest/plugin-auth
+  plugin-ldap/          @ldap-rest/plugin-ldap
+  plugin-scim/          @ldap-rest/plugin-scim
+  plugin-storage/       @ldap-rest/plugin-storage
+  plugin-twake/         @ldap-rest/plugin-twake
+  plugin-misc/          @ldap-rest/plugin-misc
+  browser/              @ldap-rest/browser
+  schemas/              @ldap-rest/schemas
+  ldap-rest/            umbrella package (CLI and re-exports)
+```
+
+Rules:
+
+- `core` depends on no family; a family depends on no other family. Cross-family
+  needs go through services (`src/lib/services`) or hooks.
+- `TwakeGroups extends LdapGroups` is either the one documented exception or
+  the shared base moves to `core`.
+- `ldap-rest` stays the entry package: it depends on every package, keeps the
+  CLI and the `core/…` namespace, and re-exports the former sub-paths
+  (`ldap-rest/plugin-auth-authzlinid1`, …). The split is therefore not breaking
+  for users.
+- The core parser accepts an injected `OptionSet`; the umbrella composes the
+  option sets of every family. `Config` may stay a type-only aggregate in
+  `core`, but runtime option imports leave the core.
+- Each package builds on its own with a shared configuration; the umbrella
+  re-exports. The Twake-specific `bin/` scripts move to their package or to a
+  `@ldap-rest/cli` package.
+
+A package per plugin (`@ldap-rest/authz-linid1`, …) is possible, but start with
+families and extract optional plugins individually later. Otherwise the first
+day costs 66 packages and 66 release cycles.
+
+## Phases
+
+### Phase 0 — Guardrails and quick wins
+
+1. [#603]: enable the type-checked rules on `test/**/*.ts`, fix the 31
+   `no-floating-promises` and 24 `await-thenable` reports, add the block to CI.
+2. [#549], part 1: `docs/architecture/README.md` (module map, life of a
+   request, life of a write) and the decision records for the decisions already
+   in place. Add `scripts/check-comments.sh` with a baseline that may only
+   shrink. The GitHub ruleset change can land separately.
+3. [#595], part 1: `@microsoft/api-extractor` on the five main entry points
+   (`ldap-rest`, `./plugin`, `./hooks`, `./ldapactions`,
+   `./expressformatedresponses`), reports under `etc/api/`, wired into the
+   `contracts` job. The 66 `./plugin-*` entries wait for phase 3.
+
+Outcome: CI catches regressions, the current architecture is documented, and
+the public types have a baseline.
+
+### Phase 1 — Decouple the core
+
+1. [#593]:
+   - typed entity registry replacing the six hand-written loops;
+   - `GroupsApi`, `OrganizationsApi`, `TrashApi`, `PasswordPolicyApi`,
+     `TwakeGroupsApi`, `AuthenticatorsInfo` service interfaces;
+   - replace the 68 `loadedPlugins` reads and the 17 `requirePlugin` uses;
+   - move `ChangesToNotify` out of `plugins/ldap/onChange.ts` and the SCIM
+     types out of `plugins/scim/` into `src/lib/`;
+   - ESLint: forbid `loadedPlugins` under `src/plugins/**` and imports between
+     plugin families.
+2. [#594]: extract the operation pipeline into `src/lib/ldap/operations.ts`,
+   bring `ldapActions.ts` under 400 lines, add the file-size test, move the
+   ESLint exemption, add the type test on `ldap-rest/ldapactions`.
+3. Options refactor (needs its own issue): split `src/config/args.ts` into core
+   options and per-family option sets; let the parser/`DM` accept an
+   `OptionSet`; move `priority.json` into the core or make it a parameter.
+
+Outcome: `src/hooks.ts` imports no plugin, the core reads no `loadedPlugins`,
+families do not import each other, and `ldapActions` is a stable façade.
+
+### Phase 2 — Workspaces and extraction
+
+1. Set up npm workspaces, `packages/`, a shared `tsconfig` and per-package
+   builds.
+2. Extract `@ldap-rest/core` first, with the `ldap-rest` umbrella depending on
+   it and re-exporting the existing entry points.
+3. Extract the families in dependency order: storage → auth → ldap → scim →
+   twake → misc.
+4. Extract `browser` and `schemas`.
+5. After each step: `npm run test:dev`, `npm run check`,
+   `npm run check:openapi`, `npm run check:options`, and the `contracts` job.
+6. Update the Dockerfile, the `bin/` scripts, the examples and the docs.
+
+Outcome: a modular repository, with `ldap-rest` still installable and
+compatible.
+
+### Phase 3 — Contracts and finalization
+
+1. [#595], part 2: one api-extractor report per sub-path, including the
+   `./plugin-*` entries, and non-additive diffs refused by `contracts`.
+2. [#549], part 2: the modularization decision record, a shrinking comment
+   baseline, and the `require_code_owner_review` ruleset.
+3. Publish the scoped packages and document the deprecation policy for the
+   former sub-paths.
+4. Close [#397].
+
+## Branch strategy
+
+Phase 0 lands on `master`: it is non-breaking, and #603 fixes test bugs that
+matter to the default branch too. Merge `master` into `v3.0` before phase 1,
+so the 3.0 work starts from a green, guarded base. Phases 1 to 3 land on
+`v3.0`.
+
+## Order
+
+```text
+#603 ───────────────┐
+#549 (part 1) ──────┼──> Phase 0
+#595 (part 1) ──────┘
+                     │
+#593 ────────────────┼──> Phase 1 ──> #397 (Phase 2) ──> #595/#549 (part 2)
+#594 ────────────────┘
+```
+
+[#603] and [#549] part 1 can start in parallel. [#595] part 1 is a short
+spike. [#593] and [#594] can then run in parallel, but both touch the core:
+freeze new cross-family imports and new `loadedPlugins` reads from the start of
+phase 1.
+
+## Decisions to make
+
+1. **Granularity**: packages per family (recommended) or one package per plugin
+   from the start?
+2. **Versioning**: a non-breaking internal split in 2.x with the umbrella
+   (recommended), or 3.0.0 with the former sub-paths removed?
+3. **`TwakeGroups extends LdapGroups`**: documented exception, or move the
+   shared base into `core`?
+4. **`Config` type**: type-only aggregate in `core` (recommended to start), or
+   split per package with declaration merging?
+5. **Build**: Rollup per package (consistent with today) or `tsc` with
+   generated exports?
+
+## First actions
+
+1. Retarget [#397] and add the package map and the dependency rule to it.
+2. Open sub-issues for [#593] and [#594]; both are too large for one pull
+   request.
+3. Start [#603] and [#549] part 1 in parallel.
+4. Spike [#595] on the five main entry points.
+5. Then [#593]/[#594], then the package extraction.
+
+[#397]: https://github.com/linagora/ldap-rest/issues/397
+[#549]: https://github.com/linagora/ldap-rest/issues/549
+[#593]: https://github.com/linagora/ldap-rest/issues/593
+[#594]: https://github.com/linagora/ldap-rest/issues/594
+[#595]: https://github.com/linagora/ldap-rest/issues/595
+[#603]: https://github.com/linagora/ldap-rest/issues/603

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

@@ -24,7 +24,8 @@ subscriber answers:
 A chained hook is handed its arguments as one value, a tuple when it has
 several. A notified hook is handed them one by one: its subscriber is
 `(dn, entry, context) => …`, never `([dn, entry], context) => …` — that form
-still compiles, the parameters being bivariant, but then reads the DN's first
+still compiles without annotation, since its parameter takes the declared
+`string` and a string can be destructured, but then reads the DN's first
 character as the DN.
 
 - **Chained.** The value goes from one subscriber to the next, each getting
@@ -60,7 +61,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 +119,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

package/docs/plugin-development/options.md

@@ -42,17 +42,43 @@ export type ExampleOptions = OptionsOf<typeof exampleOptions>;
 The key is the `Config` name: `example_timeout` is `--example-timeout`,
 `DM_EXAMPLE_TIMEOUT` when the descriptor names that variable.
 
+### Deprecating an option
+
+Rename an option by giving the old name as an alias: the parser still reads
+it, and the server warns once at startup. Keep the alias for two minor
+releases, as [CONTRIBUTING.md](../../CONTRIBUTING.md#deprecating-a-published-contract)
+requires.
+
+```typescript
+export const exampleOptions = defineOptions({
+  example_url: opt.string({
+    env: 'DM_EXAMPLE_URL',
+    aliases: ['example-uri'],
+    envAliases: ['DM_EXAMPLE_URI'],
+  }),
+});
+```
+
+A CLI alias takes one value per occurrence, as the singular form does, and an
+array option's plural form has no alias: renaming it is a breaking change. An
+environment alias is read when `env` is unset, or empty for a type where an
+empty value means nothing, and only for a non-array option when its canonical
+CLI name is absent; an array option combines the environment value with the
+CLI one, so its alias is still read.
+
 Each declaration takes:
 
-| Field      | Meaning                                                             |
-| ---------- | ------------------------------------------------------------------- |
-| `env`      | Environment variable read when the CLI does not set the option      |
-| `default`  | Value kept when neither the CLI nor the environment sets the option |
-| `required` | Refuse an empty value instead of reading it as unset                |
-| `plural`   | Array only: CLI name of the plural form, without the leading `--`   |
-| `kind`     | Array only: how a value splits, see `ArrayKind` in `parseConfig.ts` |
-| `min/max`  | Number only: bounds checked when the option is read                 |
-| `choices`  | String only: the values the option accepts                          |
+| Field        | Meaning                                                               |
+| ------------ | --------------------------------------------------------------------- |
+| `env`        | Environment variable read when the CLI does not set the option        |
+| `default`    | Value kept when neither the CLI nor the environment sets the option   |
+| `required`   | Refuse an empty value instead of reading it as unset                  |
+| `plural`     | Array only: CLI name of the plural form, without the leading `--`     |
+| `kind`       | Array only: how a value splits, see `ArrayKind` in `parseConfig.ts`   |
+| `min/max`    | Number only: bounds checked when the option is read                   |
+| `choices`    | String only: the values the option accepts                            |
+| `aliases`    | Former CLI names still accepted, without the leading `--`             |
+| `envAliases` | Former environment variables still accepted, read when `env` is unset |
 
 ## Reading options
 
@@ -103,7 +129,8 @@ moved. A migrated plugin no longer reads them: it uses `options()`.
 
 Plugins outside the repository cannot add to `args.ts` yet, but they can
 declare options the same way and name them in `optionDefinitions`: the startup
-report subtracts those keys, and `options()` reads a declared `env` variable
-when the parser did not carry the key. An option without a declaration still
-reaches `this.config` from an unknown `--key value` pair, and the startup
-report names it.
+report subtracts those keys and their aliases, and `options()` reads a declared
+`env` variable or a deprecated CLI alias the parser did not carry, warning at
+startup for the alias as it does for a core option. An option without a
+declaration still reaches `this.config` from an unknown `--key value` pair, and
+the startup report names it.

package/docs/plugin-development/services.md

@@ -0,0 +1,95 @@
+# Plugin services
+
+A plugin sometimes needs what another plugin holds: the group operations, the
+entity schemas, the trash. A service is a typed interface a plugin provides
+under a token, and another plugin reaches with `this.service(token)`.
+
+The token carries the interface. The compiler checks that an instance bound
+with `with()` answers it, and gives a consumer the type it declared. Whether a
+provider exists is a runtime question: a plugin that stops declaring the token
+still compiles, and its consumers get `null` and a warning. The plugin
+registry name stays what it is for: loading a plugin and naming it in the
+logs.
+
+## Declaring a service
+
+Put the token and its interface in a module both sides import — a plugin
+family's own service in its own module. A service shared between families is
+declared in `src/lib/services/` and re-exported from `ldap-rest/plugin`, one
+of the package's entry points; a module under `src/lib/` has no export path of
+its own.
+
+```typescript
+import { serviceToken } from 'ldap-rest/plugin';
+
+export interface GroupsApi {
+  listGroups(): Promise<string[]>;
+}
+
+export const GroupsService = serviceToken<GroupsApi>('groups');
+```
+
+Declare a token once. The object is the registry key; calling `serviceToken`
+again under the same name declares another service, not the same one. The name
+only identifies it in the logs.
+
+## Providing a service
+
+Bind the plugin instance to each token it provides:
+
+```typescript
+import DmPlugin from 'ldap-rest/plugin';
+
+export default class LdapGroups extends DmPlugin {
+  name = 'ldapGroups';
+  provides = [GroupsService.with(this)];
+
+  async listGroups(): Promise<string[]> {
+    /* … */
+  }
+}
+```
+
+`with(this)` is checked by the compiler: an instance that does not answer the
+interface does not compile. A plugin can provide several services. A service
+is registered once its plugin's registration completes — after `api()` and
+the hooks — so a consumer loaded afterwards finds it, and a provider does not
+find its own service there. A plugin needing another one declares it in
+[`dependencies`](dependencies.md#explicit-dependencies) so that it loads
+first.
+
+The first provider to register wins. A second one offering the same token is
+ignored and named in a warning: which one answered would otherwise depend on
+load order. Loading the same module twice under two names gives two instances
+but one module-level token, so the second instance cannot provide it either.
+
+When a host registers a plugin after startup, its `assertComposition` runs
+before the service is registered, so a provider does not find its own service
+there; the configuration's plugins are all registered before their
+`assertComposition` runs.
+
+## Consuming a service
+
+```typescript
+const groups = this.service(GroupsService);
+if (!groups) {
+  // Nothing provides it: the plugin skips the feature it would serve
+  return;
+}
+await groups.listGroups();
+```
+
+`service()` answers the provided instance, or `null` when nothing provides the
+token. It logs one warning per plugin and service rather than one per call. A
+plugin that cannot work without a service declares the provider in
+`dependencies`, checks the answer in `assertComposition`, and throws naming the
+service — that stops the server at startup instead of leaving a feature
+silently absent. A constructor runs before the dependencies load, so it cannot
+be the place for that check.
+
+The registry belongs to the server and is shared by the views `withConfig`
+builds for plugins loaded with overrides. It has no removal: a plugin
+registers once and keeps its services for the life of the server.
+
+`this.requirePlugin(name)` remains for a plugin whose interface is not yet
+declared as a service; new code reaches another plugin through a token.

package/docs/usage/operations.md

@@ -53,6 +53,18 @@ The image runs as its unprivileged `node` user: with `docker run`, a
 `DM_PORT` below 1024 stops the server at startup, where the default 8081
 changes nothing.
 
+The image is built in two stages: a builder produces the package and installs
+its production dependencies, the runtime stage copies them and carries no
+compiler nor package manager cache. The runtime stage upgrades the Alpine
+packages of its base image with `apk upgrade --no-cache`, so a security fix
+published after the base image was built still reaches the image: two builds
+from the same digest may differ in those packages. Its base image is pinned by
+digest in `scripts/buildDockerfile.ts`, so the image built is the one reviewed
+even if the tag moves; the digest follows the tag it names, taken from the
+[Docker Hub tag page](https://hub.docker.com/_/node/tags?name=25-alpine) and
+updated by hand with it. Dependabot ignores the image: it would open a change
+to the generated `Dockerfile`, which the drift check refuses.
+
 ### What the shipped plugins report
 
 | Plugin           | `degraded` when                                                                                                                                                                                             |

package/docs/usage/plugins/integrations/instances.md

@@ -19,7 +19,13 @@ gets no instance.
   An entry holding `--twake-instance-skip-value` in
   `--twake-instance-skip-attribute`, a technical account for instance, gets
   none, and neither does a tombstone
-  (`--twake-lifecycle-deleted-attribute`) put back in place.
+  (`--twake-lifecycle-deleted-attribute`) put back in place. Each expression
+  is tried against the canonical DN first, then against the DN as sent: an
+  account created under a branch written with other spacing or case is still
+  one, and an expression written with the directory's own spelling (`\2C`, a
+  doubled space) still matches. An expression naming a value that holds a
+  comma writes it `\2C` or `\,`: a value comma never stands in for an RDN
+  separator in the form matched.
 - The address (`--twake-instance-fqdn-attribute`) and the mark
   (`--twake-instance-sent-attribute`) are this plugin's to write: an add that
   carries them has them removed, and an address written by a modify is taken
@@ -80,8 +86,10 @@ before it takes its members' `user.created`. Then `organization.created` is
 published on the b2b exchange, and the entry is marked. The message carries
 the organization's id, address, domain, and its name as `organization`, read
 from `--twake-instance-organization-name-attribute`, which
-`ensureOrganization` fills from `name` when the entry has none. The mark, not
-the address, says the organization is done.
+`ensureOrganization` fills from `name` when the entry has none. An id captured
+from a `--twake-instance-dn` group is read from the organization entry when
+one exists, so the case a caller spells the branch in is not sent. The mark,
+not the address, says the organization is done.
 
 With the Cloudery, a member's `user.created` waits for its organization's: a
 member under an organization entry that is not marked yet gets its address

package/docs/usage/plugins/integrations/lifecycle-events.md

@@ -110,7 +110,10 @@ operational one such as `pwdAccountLockedTime` is seen on both sides.
   means entries are never tombstones, and only a removal publishes `deleted`.
 - `--twake-lifecycle-deleted-at-attribute`,
   `--twake-lifecycle-deleted-at-format` (`iso8601`, the default, or
-  `generalizedTime`): the deletion date. It is always published as ISO 8601.
+  `generalizedTime`): the deletion date. It is read whether it is written as
+  a GeneralizedTime or as an ISO 8601 date, and always published as ISO 8601;
+  a value of neither shape is left out. A GeneralizedTime needs its zone; an
+  ISO 8601 date and time without one is read in the server's time zone.
 - `--twake-lifecycle-member-attribute` (default `member`): the attribute
   `memberAdded`, `memberRemoved` and member lists read.
 - `--twake-lifecycle-rules`: a JSON file, or the JSON itself.

package/docs/usage/plugins/integrations/scim.md

@@ -223,16 +223,17 @@ and `--scim-group-mapping`.
 
 Each element of `entries` is a `MappingEntry` with the following optional fields:
 
-| Field           | Purpose                                                                                                              |
-| --------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `scim`          | **Required.** Top-level SCIM attribute name (`userName`, `displayName`, `emails`, …).                                |
-| `ldap`          | Simple 1:1 mapping to an LDAP attribute.                                                                             |
-| `ldapPrimary`   | For multi-valued SCIM attributes (`emails`, `phoneNumbers`, …), the LDAP attribute that stores the _primary_ value.  |
-| `ldapSecondary` | LDAP attribute that stores the _non-primary_ values of the same SCIM attribute (array).                              |
-| `sub`           | Object that maps SCIM sub-attributes to LDAP attributes. Used for complex SCIM values like `name.familyName` → `sn`. |
-| `multi`         | `"array"` or `"single"` (default) — hints array serialization for `ldap`.                                            |
-| `readOnly`      | `true` to skip this attribute on write (create/update ignore it).                                                    |
-| `operational`   | `true` for LDAP operational attributes (e.g. `entryUUID`) — loaded on read only.                                     |
+| Field           | Purpose                                                                                                                       |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `scim`          | **Required.** Top-level SCIM attribute name (`userName`, `displayName`, `emails`, …).                                         |
+| `ldap`          | Simple 1:1 mapping to an LDAP attribute.                                                                                      |
+| `ldapPrimary`   | For multi-valued SCIM attributes (`emails`, `phoneNumbers`, …), the LDAP attribute that stores the _primary_ value.           |
+| `ldapSecondary` | LDAP attribute that stores the _non-primary_ values of the same SCIM attribute (array).                                       |
+| `sub`           | Object that maps SCIM sub-attributes to LDAP attributes. Used for complex SCIM values like `name.familyName` → `sn`.          |
+| `subDn`         | Sub-attribute names in `sub` whose value is a DN (for example `["value"]` for `manager`); they are held to RFC 4514 on write. |
+| `multi`         | `"array"` or `"single"` (default) — hints array serialization for `ldap`.                                                     |
+| `readOnly`      | `true` to skip this attribute on write (create/update ignore it).                                                             |
+| `operational`   | `true` for LDAP operational attributes (e.g. `entryUUID`) — loaded on read only.                                              |
 
 ### Merging
 
@@ -269,7 +270,8 @@ override only what's different and inherit the rest.
     },
     {
       "scim": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
-      "sub": { "value": "manager" }
+      "sub": { "value": "manager" },
+      "subDn": ["value"]
     }
   ]
 }
@@ -317,7 +319,11 @@ of them; a complex attribute takes an object whose sub-attributes are scalars
 multi-valued complex attribute such as `emails` takes a list of objects whose
 `value` is a scalar. Anything else is answered
 `400 invalidValue`, as is a PATCH operation that is not an object or whose
-`op` is not a string.
+`op` is not a string. A reference the mapping declares a DN (`subDn`) is
+refused with `400 invalidValue` when its value holds an escape RFC 4514 does
+not define, as the flat routes hold a client-written DN. The directory
+refuses such a value itself on an attribute of DN syntax; this names the
+escape in the SCIM answer and applies wherever the mapping declares one.
 
 A PATCH `add`, or a `remove` naming values, changes only the values it names:
 values the caller's read did not show, such as group members an
@@ -715,18 +721,14 @@ Response shape (truncated):
             "id",
             "active"
           ],
-          "mapping": [
-            /* same shape as default-mapping.json */
-          ]
+          "mapping": [/* same shape as default-mapping.json */]
         },
         {
           "id": "Group",
           "endpoint": "/scim/v2/Groups",
           "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
           "rdnAttribute": "cn",
-          "mapping": [
-            /* ... */
-          ]
+          "mapping": [/* ... */]
         }
       ],
       "idStrategy": "rdn",

package/docs/usage/plugins/integrations/tombstone.md

@@ -10,10 +10,13 @@ is old enough, or right away when forced.
 
 ## Behaviour
 
-- A delete of an entry whose DN matches `--twake-tombstone-dn` writes, in one
-  modify: the deleted attribute, the deletion date (now), the reason, the
-  lock, and removes `--twake-tombstone-clear-attributes`. Other entries are
-  deleted as usual.
+- A delete of an entry whose DN matches `--twake-tombstone-dn` — under any
+  spelling the directory folds, so spaces, case and escapes do not matter —
+  writes, in one modify: the deleted attribute, the deletion date (now), the
+  reason, the lock, and removes `--twake-tombstone-clear-attributes`. Other
+  entries are deleted as usual. A multi-valued RDN may not match: an
+  expression anchored on `uid=` misses a DN written `cn=…+uid=…`, and that
+  delete removes the entry for good.
 - A delete of an existing tombstone writes nothing and answers as a delete.
   It fires the `twakedeletionreplay` hook with the tombstone, so
   [lifecycle events](lifecycle-events.md) publishes the deletion again, with
@@ -62,8 +65,9 @@ Content-Type: application/json
 
 - `200`: erased.
 - `404`: no tombstone at this DN.
-- `409`: the deletion is younger than `--twake-tombstone-erase-min-age` and
-  `force` is not true.
+- `409`: `force` is not true, and either the deletion is younger than
+  `--twake-tombstone-erase-min-age` or its date cannot be read as
+  [lifecycle events](lifecycle-events.md) reads it.
 
 Other plugins call `erase(dn, { force, req })`.
 

package/docs/usage/plugins/ldap/flat-generic.md

@@ -453,7 +453,14 @@ Content-Type: application/json
 
 The identifier may also be the whole DN of the entry, in the entity's
 branch: `"uid": "uid=Smith\\,John,ou=users,dc=example,dc=com"` creates the
-entry `Smith,John`, whose DN spells the name with its escapes.
+entry `Smith,John`, whose DN spells the name with its escapes. The DN must
+use the escapes RFC 4514 defines; an escape it does not define (`\q`) is
+refused with a `400`. Send the bare value to have the server escape it.
+
+The name written is the value the RDN gives under the folding the directory
+applies (Unicode NFKC, and its insignificant spaces): `uid=\ zoë` and
+`uid=zoë` name one entry, written `uid=zoë`, and a name sent decomposed is
+stored composed.
 
 ### Modify Entry