ldap-rest 0.6.2 → 0.8.0

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

@@ -41,27 +41,30 @@ All SCIM endpoints sit behind the auth middleware registered before the plugin
 
 ### CLI / environment
 
-| Argument                       | Environment                     | Default                                            | Description                                                            |
-| ------------------------------ | ------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
-| `--scim-prefix`                | `DM_SCIM_PREFIX`                | `/scim/v2`                                         | Base URL path for all SCIM endpoints                                   |
-| `--scim-user-base`             | `DM_SCIM_USER_BASE`             | `{ldap_base}`                                      | LDAP branch containing users                                           |
-| `--scim-group-base`            | `DM_SCIM_GROUP_BASE`            | `{ldap_base}`                                      | LDAP branch containing groups                                          |
-| `--scim-user-base-template`    | `DM_SCIM_USER_BASE_TEMPLATE`    | —                                                  | DN template with `{user}` placeholder (see _multi-tenant_)             |
-| `--scim-group-base-template`   | `DM_SCIM_GROUP_BASE_TEMPLATE`   | —                                                  | Same for groups                                                        |
-| `--scim-base-map`              | `DM_SCIM_BASE_MAP`              | —                                                  | Path to JSON file mapping authenticated user → `{userBase, groupBase}` |
-| `--scim-user-object-class`     | `DM_SCIM_USER_OBJECT_CLASSES`   | `top, inetOrgPerson, organizationalPerson, person` | Object classes for created Users                                       |
-| `--scim-user-rdn-attribute`    | `DM_SCIM_USER_RDN_ATTRIBUTE`    | `uid`                                              | RDN attribute for Users                                                |
-| `--scim-group-object-class`    | `DM_SCIM_GROUP_OBJECT_CLASSES`  | `top, groupOfNames`                                | Object classes for created Groups                                      |
-| `--scim-group-rdn-attribute`   | `DM_SCIM_GROUP_RDN_ATTRIBUTE`   | `cn`                                               | RDN attribute for Groups                                               |
-| `--scim-id-attribute`          | `DM_SCIM_ID_ATTRIBUTE`          | `rdn`                                              | `rdn` (default) or `entryUUID` for SCIM `id`                           |
-| `--scim-user-mapping`          | `DM_SCIM_USER_MAPPING`          | —                                                  | Path to JSON mapping override                                          |
-| `--scim-group-mapping`         | `DM_SCIM_GROUP_MAPPING`         | —                                                  | Same for Groups                                                        |
-| `--scim-max-results`           | `DM_SCIM_MAX_RESULTS`           | `200`                                              | Maximum page size (caps `count`)                                       |
-| `--scim-max-scanned`           | `DM_SCIM_MAX_SCANNED`           | `10000`                                            | Entries a list may walk before answering `400 tooMany`                 |
-| `--scim-bulk-max-operations`   | `DM_SCIM_BULK_MAX_OPERATIONS`   | `100`                                              | Max `/Bulk` operations per request                                     |
-| `--scim-bulk-max-payload-size` | `DM_SCIM_BULK_MAX_PAYLOAD_SIZE` | `1048576`                                          | Max `/Bulk` payload size in bytes                                      |
-| `--scim-etag`                  | `DM_SCIM_ETAG`                  | `false`                                            | Advertise ETag support in discovery (not yet implemented)              |
-| `--scim-base-url`              | `DM_SCIM_BASE_URL`              | auto from request                                  | Override external base URL for `meta.location` values                  |
+| Argument                             | Environment                           | Default                                            | Description                                                                                      |
+| ------------------------------------ | ------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `--scim-prefix`                      | `DM_SCIM_PREFIX`                      | `/scim/v2`                                         | Base URL path for all SCIM endpoints                                                             |
+| `--scim-user-base`                   | `DM_SCIM_USER_BASE`                   | `{ldap_base}`                                      | LDAP branch containing users                                                                     |
+| `--scim-group-base`                  | `DM_SCIM_GROUP_BASE`                  | `{ldap_base}`                                      | LDAP branch containing groups                                                                    |
+| `--scim-user-base-template`          | `DM_SCIM_USER_BASE_TEMPLATE`          | —                                                  | DN template with `{user}` placeholder (see _multi-tenant_)                                       |
+| `--scim-group-base-template`         | `DM_SCIM_GROUP_BASE_TEMPLATE`         | —                                                  | Same for groups                                                                                  |
+| `--scim-base-map`                    | `DM_SCIM_BASE_MAP`                    | —                                                  | Path to JSON file mapping authenticated user → `{userBase, groupBase}`                           |
+| `--scim-user-object-class`           | `DM_SCIM_USER_OBJECT_CLASSES`         | `top, inetOrgPerson, organizationalPerson, person` | Object classes for created Users                                                                 |
+| `--scim-user-rdn-attribute`          | `DM_SCIM_USER_RDN_ATTRIBUTE`          | `uid`                                              | RDN attribute for Users                                                                          |
+| `--scim-user-lock-attribute`         | `DM_SCIM_USER_LOCK_ATTRIBUTE`         | `pwdAccountLockedTime`                             | LDAP attribute whose presence marks a User as `active: false`                                    |
+| `--scim-user-lock-value`             | `DM_SCIM_USER_LOCK_VALUE`             | —                                                  | Value written to that attribute when deactivating (required unless the attribute is the default) |
+| `--scim-group-object-class`          | `DM_SCIM_GROUP_OBJECT_CLASSES`        | `top, groupOfNames`                                | Object classes for created Groups                                                                |
+| `--scim-group-rdn-attribute`         | `DM_SCIM_GROUP_RDN_ATTRIBUTE`         | `cn`                                               | RDN attribute for Groups                                                                         |
+| `--scim-group-external-id-attribute` | `DM_SCIM_GROUP_EXTERNAL_ID_ATTRIBUTE` | —                                                  | LDAP attribute storing a Group's `externalId` (unset: not supported)                             |
+| `--scim-id-attribute`                | `DM_SCIM_ID_ATTRIBUTE`                | `rdn`                                              | `rdn` (default) or `entryUUID` for SCIM `id`                                                     |
+| `--scim-user-mapping`                | `DM_SCIM_USER_MAPPING`                | —                                                  | Path to JSON mapping override                                                                    |
+| `--scim-group-mapping`               | `DM_SCIM_GROUP_MAPPING`               | —                                                  | Same for Groups                                                                                  |
+| `--scim-max-results`                 | `DM_SCIM_MAX_RESULTS`                 | `200`                                              | Maximum page size (caps `count`)                                                                 |
+| `--scim-max-scanned`                 | `DM_SCIM_MAX_SCANNED`                 | `10000`                                            | Entries a list may walk before answering `400 tooMany`                                           |
+| `--scim-bulk-max-operations`         | `DM_SCIM_BULK_MAX_OPERATIONS`         | `100`                                              | Max `/Bulk` operations per request                                                               |
+| `--scim-bulk-max-payload-size`       | `DM_SCIM_BULK_MAX_PAYLOAD_SIZE`       | `1048576`                                          | Max `/Bulk` payload size in bytes                                                                |
+| `--scim-etag`                        | `DM_SCIM_ETAG`                        | `false`                                            | Advertise ETag support in discovery (not yet implemented)                                        |
+| `--scim-base-url`                    | `DM_SCIM_BASE_URL`                    | auto from request                                  | Override external base URL for `meta.location` values                                            |
 
 ### Authorization
 
@@ -110,27 +113,91 @@ All responses have `Content-Type: application/scim+json`.
 
 ### Default mapping (LDAP ⇄ SCIM User)
 
-| SCIM                                 | LDAP                                            |
-| ------------------------------------ | ----------------------------------------------- |
-| `id`                                 | `uid` (or `entryUUID`)                          |
-| `userName`                           | `uid`                                           |
-| `externalId`                         | `employeeNumber`                                |
-| `name.familyName`                    | `sn`                                            |
-| `name.givenName`                     | `givenName`                                     |
-| `name.formatted`                     | `cn`                                            |
-| `displayName`                        | `displayName`                                   |
-| `title`                              | `title`                                         |
-| `preferredLanguage`                  | `preferredLanguage`                             |
-| `emails[primary=true].value`         | `mail`                                          |
-| `emails[primary=false].value`        | `mailAlternateAddress`                          |
-| `phoneNumbers[primary=true].value`   | `telephoneNumber`                               |
-| `phoneNumbers[primary=false].value`  | `mobile`                                        |
-| `active`                             | pseudo (false if `pwdAccountLockedTime` is set) |
-| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`           |
+| SCIM                                 | LDAP                                        |
+| ------------------------------------ | ------------------------------------------- |
+| `id`                                 | `uid` (or `entryUUID`)                      |
+| `userName`                           | `uid`                                       |
+| `externalId`                         | `employeeNumber`                            |
+| `name.familyName`                    | `sn`                                        |
+| `name.givenName`                     | `givenName`                                 |
+| `name.formatted`                     | `cn`                                        |
+| `displayName`                        | `displayName`                               |
+| `title`                              | `title`                                     |
+| `preferredLanguage`                  | `preferredLanguage`                         |
+| `emails[primary=true].value`         | `mail`                                      |
+| `emails[primary=false].value`        | `mailAlternateAddress`                      |
+| `phoneNumbers[primary=true].value`   | `telephoneNumber`                           |
+| `phoneNumbers[primary=false].value`  | `mobile`                                    |
+| `active`                             | pseudo (false if the lock attribute is set) |
+| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`       |
 
 Override with `--scim-user-mapping /path/to/user-mapping.json` (same schema as
 `static/schemas/scim/default-mapping.json`).
 
+## Deactivating an account (`active`)
+
+SCIM models account status with the boolean `active` (RFC 7643 §4.1.1), and it
+is how Okta, Entra ID and JumpCloud disable a user — they PATCH `active` to
+`false` rather than DELETE the resource.
+
+LDAP has no single equivalent, so the plugin models it on the **presence of one
+attribute**: present means locked, absent means active.
+
+| SCIM              | LDAP                                            |
+| ----------------- | ----------------------------------------------- |
+| `"active": false` | write `--scim-user-lock-value` to the attribute |
+| `"active": true`  | remove the attribute                            |
+| attribute absent  | `"active": true`                                |
+
+The default targets the ppolicy overlay:
+
+```bash
+--scim-user-lock-attribute pwdAccountLockedTime
+--scim-user-lock-value     000001010000Z          # "locked forever"
+```
+
+`pwdAccountLockedTime` only exists when slapd loads the ppolicy overlay. On a
+directory without it — plain OpenLDAP, 389-ds, AD — the directory refuses the
+write against its schema, and the plugin answers `400 invalidValue` naming
+the attribute and the flags to change, on `/Bulk` as on the single-resource
+routes. Point the two flags elsewhere:
+
+```bash
+--scim-user-lock-attribute nsAccountLock
+--scim-user-lock-value     TRUE
+```
+
+**Name the value whenever you name the attribute.** `000001010000Z` is the
+ppolicy convention and means nothing to any other attribute: 389-ds reads
+`nsAccountLock` as locked only when it says `true`. Setting the attribute
+alone would write a value the directory ignores — every deactivation answers
+200 and reads back `active: false` while the account keeps binding. The
+plugin refuses to start instead.
+
+Two more pairings get a warning at startup rather than a refusal, because
+neither can be told apart from a deliberate local schema:
+
+- the ppolicy value `000001010000Z` pinned on some other attribute, which is
+  what a deployment template that always sets both flags produces by default
+- a value `pwdAccountLockedTime` cannot hold, `TRUE` for instance: it holds a
+  GeneralizedTime
+
+**None of this can tell whether your directory honours the value you chose.**
+The checks are on the shape of the configuration. `active` is read back from
+the mere presence of the attribute, so a value the directory stores and
+ignores still reads as `false`. Verify once, by hand, that a deactivation
+actually prevents a bind.
+
+`active` is not a mapping entry and must not be added to a mapping file: it is
+handled by these two flags on every path — create, PUT, PATCH and the
+`active eq true|false` filter alike.
+
+PUT is a full replacement (RFC 7644 §3.5.1) for every attribute except this
+one: a body that omits `active` leaves the lock as it stands. Clearing it
+would release locks SCIM never set — a ppolicy auto-lockout, or one an
+administrator placed — so a routine profile sync would defeat the
+brute-force control. Send `"active": true` to reactivate deliberately.
+
 ## Writing a custom mapping schema
 
 The mapping file is a plain JSON document describing how each SCIM attribute is
@@ -247,6 +314,23 @@ adjust the loader). Exposing a schema there is **independent** from the
 LDAP↔SCIM projection: the schema file describes the public SCIM contract, the
 mapping file describes the internal translation.
 
+### Group `externalId`
+
+RFC 7643 §3.1 defines `externalId` as the **provisioning client's** identifier —
+the id Okta or Entra ID keeps for its own copy of the resource, which it later
+uses to find the group again (`filter=externalId eq "…"`).
+
+For Users it lands in `employeeNumber`. groupOfNames has no attribute meant to
+hold one, so nothing is stored unless the deployment names an attribute:
+
+```bash
+--scim-group-external-id-attribute description
+```
+
+Without it, `externalId` sent on a Group is ignored and a filter on it answers
+`400 invalidFilter` — which is at least honest. Any free attribute of your
+group entries works; use a mapping override if you would rather name it there.
+
 ## Filter syntax
 
 SCIM filters are translated to LDAP filters (RFC 4515). Values are always escaped
@@ -259,6 +343,7 @@ via `escapeLdapFilter()` — no LDAP injection is possible.
 | `emails.value co "@example.com"` | `(mail=*@example.com*)`       |
 | `displayName pr`                 | `(displayName=*)`             |
 | `active eq true`                 | `(!(pwdAccountLockedTime=*))` |
+| `active pr`                      | `(objectClass=*)`             |
 | `a eq "x" and b eq "y"`          | `(&(a=x)(b=y))`               |
 | `not (a eq "x")`                 | `(!(a=x))`                    |
 
@@ -297,6 +382,30 @@ willing to calculate or process". Raise the flag, or narrow the query.
 If the directory's own size limit is lower than the collection, it refuses the
 search first and the answer is the same `tooMany` — raise `sizelimit` in slapd.
 
+## Partial representations (`attributes` / `excludedAttributes`)
+
+Any route that answers a resource accepts the two RFC 7644 §3.9 parameters —
+the lists, the single-resource GETs, and the POST/PUT/PATCH answers alike.
+
+```bash
+curl '.../Users/alice?attributes=userName,name.familyName'
+curl '.../Users?excludedAttributes=emails'
+```
+
+- `attributes` replaces the default set: only what you name comes back.
+- `excludedAttributes` keeps the default set minus what you name.
+- Both accept standard attribute notation, so `name.familyName` and
+  `emails.value` narrow a complex or multi-valued attribute rather than
+  dropping it whole, and a core schema URN prefix is accepted and stripped.
+- `id` and `schemas` are `returned: always` (RFC 7643 §7): they survive an
+  exclusion and are added back to an `attributes` list.
+- `meta` is `returned: default`, so an `attributes` list that does not name it
+  does not get it. Ask for `meta` explicitly if you need `meta.location`.
+- The two are mutually exclusive; sending both answers `400 invalidValue`.
+
+The projection applies to the response only — the LDAP search still reads the
+attributes the mapping needs.
+
 ## Multi-tenant: per-user LDAP bases
 
 SCIM does not expose any tenant concept to clients — resource `id`s are opaque

package/docs/usage/plugins/ldap/README.md

@@ -4,17 +4,19 @@ Plugins for LDAP entity management.
 
 ## Overview
 
-| Plugin                                | Entity                   | Features                            |
-| ------------------------------------- | ------------------------ | ----------------------------------- |
-| [flat-generic](flat-generic.md)       | Users, Positions, Custom | Schema-driven, Validation, Pointers |
-| [groups](groups.md)                   | Groups                   | Member validation, Nested groups    |
-| [organizations](organizations.md)     | Organizational Units     | Tree navigation, Search             |
-| [bulk-import](bulk-import.md)         | All (bulk operations)    | CSV import, Template generation     |
-| [trash](trash.md)                     | All (soft delete)        | Trash system, Recovery              |
-| [external-users](external-users.md)   | Contacts                 | Automatic creation                  |
-| [on-change](on-change.md)             | All                      | Change detection                    |
-| [password-policy](password-policy.md) | Password management      | Expiration, Lockout, Unlock         |
-| [raw](raw.md)                         | Whole directory (read)   | Root DSE, Schema, Tree, Raw search  |
+| Plugin                                    | Entity                   | Features                                |
+| ----------------------------------------- | ------------------------ | --------------------------------------- |
+| [flat-generic](flat-generic.md)           | Users, Positions, Custom | Schema-driven, Validation, Pointers     |
+| [groups](groups.md)                       | Groups                   | Member validation, Nested groups        |
+| [organizations](organizations.md)         | Organizational Units     | Tree navigation, Search                 |
+| [bulk-import](bulk-import.md)             | All (bulk operations)    | CSV import, Template generation         |
+| [trash](trash.md)                         | All (soft delete)        | Trash system, Recovery                  |
+| [external-users](external-users.md)       | Contacts                 | Automatic creation                      |
+| [on-change](on-change.md)                 | All                      | Change detection                        |
+| [enterprise-rules](enterprise-rules.md)   | All (business rules)     | Uniqueness, Mail domains, Delete guards |
+| [account-lifecycle](account-lifecycle.md) | Accounts                 | Enable/disable, Password reset          |
+| [password-policy](password-policy.md)     | Password management      | Expiration, Lockout, Unlock             |
+| [raw](raw.md)                             | Whole directory (read)   | Root DSE, Schema, Tree, Raw search      |
 
 ## API Endpoints
 

package/docs/usage/plugins/ldap/account-lifecycle.md

@@ -0,0 +1,129 @@
+# LDAP Account Lifecycle Plugin
+
+The two account operations an administrator performs most often — change an
+account's state, and reset its password — as first-class endpoints.
+
+Both are expressed against semantic roles, never attribute names. What
+"disabled" _is_ in a given directory — a DN in a nomenclature, a string, a
+boolean — is schema configuration.
+
+## Configuration
+
+```bash
+--plugin core/ldap/accountLifecycle
+```
+
+The plugin loads `core/ldap/flatGeneric` if it is not already there, and adds
+endpoints to each entity whose schema asks for them:
+
+- `POST /api/v1/ldap/{pluralName}/{id}/status` when the schema declares an
+  `accountStatus` attribute carrying named `states`
+- `POST /api/v1/ldap/{pluralName}/{id}/password` when it declares a `password`
+  attribute
+
+Changes go through the entity's own modify path, so schema validation, hooks
+and authorization apply exactly as they do to any other update.
+
+## Declaring the states
+
+```json
+{
+  "twakeAccountStatus": {
+    "type": "pointer",
+    "branch": ["ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com"],
+    "role": "accountStatus",
+    "generated": true,
+    "default": "cn=active,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+    "states": {
+      "enabled": "cn=active,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+      "disabled": "cn=disabled,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+      "noAccess": "cn=noaccess,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com",
+      "toDelete": "cn=todelete,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com"
+    }
+  }
+}
+```
+
+`enabled` and `disabled` are the names the API speaks; a deployment adds its
+own freely. `default` is what a new account gets, applied by
+[enterprise-rules](enterprise-rules.md).
+
+## Changing the state
+
+```bash
+curl -X POST http://localhost:8081/api/v1/ldap/users/alice/status \
+  -H 'Content-Type: application/json' \
+  -d '{"state": "disabled"}'
+```
+
+```json
+{ "success": true, "state": "disabled" }
+```
+
+An unknown state is refused with a `400` that names the ones this directory
+knows, so a client never has to hardcode the list:
+
+```json
+{
+  "error": "Unknown state \"retired\" for user; known states: enabled, disabled, noAccess, toDelete"
+}
+```
+
+## Resetting the password
+
+```bash
+curl -X POST http://localhost:8081/api/v1/ldap/users/alice/password \
+  -H 'Content-Type: application/json' -d '{}'
+```
+
+```json
+{ "success": true, "generated": true, "forceChange": true, "password": "xY3k…" }
+```
+
+With no `password` in the body, one is generated and returned **once** — the
+credential attributes are marked `neverReturn` in the schema precisely so a
+later read cannot hand it back. Supply `password` to set a chosen one; the
+answer then carries `"generated": false` and does not echo it.
+
+A `password` that is present has to be a non-empty string. An empty one — or
+`null`, or anything that is not text — is refused with a `400`:
+
+```json
+{
+  "error": "Field password must be a non-empty string; omit it to have one generated"
+}
+```
+
+It used to be taken as an absent one, so `{"password": ""}` answered
+`success` after setting a random credential the caller never saw: a client
+that emptied the field by accident believed it had set the password it typed.
+Omitting the field is how a generated password is asked for.
+
+`forceChange` (true by default) also writes the `passwordReset`-role attribute
+so the directory asks for a new password at next login. For a boolean
+attribute the values written are `TRUE` and `FALSE`; a directory that spells
+them otherwise says so through `states.required` and `states.cleared`.
+
+| Field         | Meaning                                             |
+| ------------- | --------------------------------------------------- |
+| `generated`   | The server chose the password                       |
+| `password`    | Present only when generated                         |
+| `forceChange` | Whether the "change at next login" flag was written |
+
+> **Note** — `pwdReset` is an operational attribute of the OpenLDAP `ppolicy`
+> overlay. Writing it requires the overlay to be loaded; without it the
+> directory answers `attribute type undefined`.
+
+## Errors
+
+| Status | When                                                           |
+| ------ | -------------------------------------------------------------- |
+| `400`  | Unknown state, or a body with no `state`                       |
+| `400`  | A `password` that is present but empty, `null` or not a string |
+| `404`  | No such account                                                |
+
+## See also
+
+- [flat-generic](flat-generic.md) — `role`, `states` and `neverReturn`
+- [enterprise-rules](enterprise-rules.md) — the default state of a new account
+- [password-policy](password-policy.md) — expiry, lockout and complexity

package/docs/usage/plugins/ldap/bulk-import.md

@@ -137,6 +137,13 @@ jdoe,John Doe,Doe,John,john.doe@example.com,password123,ou=IT,ou=organization,dc
 asmith,Alice Smith,Smith,Alice,alice.smith@example.com,secret456,ou=HR,ou=organization,dc=example,dc=com
 ```
 
+A value must sit under a column whose name is a syntactically valid LDAP
+attribute name (`mail`, `2.5.4.3`, `cn;lang-fr`). Otherwise its line fails
+with `Invalid column name` and is counted in `failed`. The check is on syntax
+only: an unknown attribute such as `maill` passes it and fails on the
+directory side. Empty cells are ignored whatever their column is called, so a
+comment column left empty, or a trailing comma, does not prevent the import.
+
 ### Special Column: `organizationDn`
 
 The `organizationDn` column is special and triggers automatic calculation of:
@@ -289,7 +296,7 @@ mail: john.doe@example.com
 userPassword: {SSHA}...
 telephoneNumber: +1-555-0100
 twakeDepartmentLink: ou=Engineering,ou=organization,dc=example,dc=com
-twakeDepartmentPath: Engineering / organization
+twakeDepartmentPath: Engineering
 ```
 
 ## Operation Modes

package/docs/usage/plugins/ldap/enterprise-rules.md

@@ -0,0 +1,167 @@
+# LDAP Enterprise Rules Plugin
+
+The business rules an enterprise directory needs on top of per-attribute
+validation: uniqueness across a shared namespace, mail addresses confined to
+the domains an organization owns, computed organization paths, normalised
+quotas, and referential-integrity guards on deletion.
+
+Every rule is driven by the loaded entity schemas. The plugin contains no
+attribute name, no domain and no nomenclature value, so the same code serves a
+directory laid out differently without a change.
+
+## Configuration
+
+```bash
+--plugin core/ldap/enterpriseRules
+```
+
+It reads the schemas already loaded by `core/ldap/flatGeneric`,
+`core/ldap/groups` and `core/ldap/organizations`, so load it alongside them.
+The organizations plugin only exposes its schema when one is given:
+
+```bash
+--organization-schema ./static/schemas/twake/organizations.json
+```
+
+| Option                               | Default             | Purpose                                                             |
+| ------------------------------------ | ------------------- | ------------------------------------------------------------------- |
+| `--enterprise-domain-name-attribute` | `associatedDomain`  | Fallback when no loaded schema declares a `domainName` role         |
+| `--enterprise-domain-link-attribute` | _(from the schema)_ | Fallback when the organization schema declares no `domainLink` role |
+| `--group-dummy-user`                 | `cn=fakeuser`       | Placeholder member that does not count towards `deleteGuard`        |
+
+## Order of evaluation
+
+Checks run **before** transformations, inside the same hook. A check therefore
+always sees the payload as the client sent it: uniqueness and domain rules
+validate the address that was submitted, never one the server has already
+rewritten, and an identifier derived from that address cannot influence the
+check that justified it.
+
+## Rules
+
+### Uniqueness
+
+```json
+{
+  "employeeNumber": { "type": "string", "unique": true },
+  "mail": {
+    "type": "string",
+    "role": "primaryEmail",
+    "unique": {
+      "attributes": ["mailAlternateAddress"],
+      "branches": ["dc=example,dc=com"]
+    }
+  }
+}
+```
+
+- `attributes` names the other attributes sharing the value namespace — a mail
+  address must not already be someone's alias.
+- `branches` widens the search beyond the entity's own branch, which is what
+  makes an address unique across accounts _and_ distribution lists.
+- `sentinel` exempts one value, for directories that use a placeholder on
+  non-individual entries.
+- `filter` narrows the search, e.g. `(objectClass=twakeAccount)`.
+
+On an update the entry being modified is excluded from the search, so
+re-sending an unchanged value never conflicts with itself.
+
+### Mail domains
+
+```json
+{
+  "mail": {
+    "mailDomainScope": "organization",
+    "allowSubdomains": true
+  }
+}
+```
+
+`organization` walks up from the entry's `organizationLink`, collecting the
+domains each ancestor declares through its `domainLink` role, up to the root of
+the tree. `directory` accepts any domain declared anywhere. When nobody
+declares a domain, no restriction applies; a domain entry whose name is `*`
+authorises every domain.
+
+The host is taken after the **last** `@`, so a domain that merely ends with an
+authorised one (`evil-example.org` against `example.org`) is refused.
+`allowSubdomains` is what lets a distribution list live at
+`all@lists.example.org` under an organization that owns `example.org`.
+
+### Computed organization path
+
+An entity declaring both an `organizationLink` and an `organizationPath` role
+gets its path filled from the organization it points at, on creation and
+whenever the link changes. Mark the path `generated` so a client cannot set it.
+
+### Normalised sizes
+
+```json
+{
+  "mailQuotaSize": {
+    "type": "number",
+    "normalize": "byteSize",
+    "default": 1000000000,
+    "hint": "Expected pattern xGB, xMB, xKB or a number of bytes"
+  }
+}
+```
+
+`5GB`, `500 MB`, `2KB` and `2048` all become a number of bytes, with decimal
+multipliers (1 GB = 10⁹ bytes) as mail servers count them. The same conversion
+applies to creations and to updates.
+
+### Server-owned defaults
+
+On creation, an attribute that is `generated` or `normalize`d and carries a
+`default` is filled when the client said nothing — which is how a new account
+lands in its initial state:
+
+```json
+{
+  "twakeAccountStatus": {
+    "type": "pointer",
+    "role": "accountStatus",
+    "generated": true,
+    "default": "cn=active,ou=twakeAccountStatus,ou=nomenclature,dc=example,dc=com"
+  }
+}
+```
+
+### Scheduled removal
+
+An `accountExpiry` attribute must not carry a date already past. The comparison
+is against the start of the current day, so scheduling something for today is
+allowed.
+
+### Deletion guards
+
+```json
+{
+  "title": { "type": "pointer", "referentialIntegrity": "restrict" },
+  "member": { "type": "array", "role": "members", "deleteGuard": "nonEmpty" }
+}
+```
+
+- `referentialIntegrity: "restrict"` refuses to delete an entry while another
+  entry still points at it — a position somebody still holds, a nomenclature
+  value still in use. Declared on the **referencing** attribute, and the
+  pointer's `branch` tells the plugin which deletions to check.
+- `deleteGuard: "nonEmpty"` refuses to delete a group that still has members.
+  The placeholder member some directories keep to satisfy `groupOfNames`
+  (`--group-dummy-user`) does not count.
+
+Both default to off: a deployment turns them on where it wants them.
+
+## Errors
+
+| Status | When                                                                          |
+| ------ | ----------------------------------------------------------------------------- |
+| `400`  | A size that is not a size, a date already past                                |
+| `409`  | A duplicate value, a mail domain outside the authorised set, a guarded delete |
+
+## See also
+
+- [flat-generic](flat-generic.md) — the schema format these markers extend
+- [account-lifecycle](account-lifecycle.md) — status changes and password resets
+- [organizations](organizations.md) — the tree the domain rule walks up