ldap-rest 0.6.2 → 0.8.0

package/docs/usage/upgrading.md

@@ -0,0 +1,444 @@
+# Upgrading
+
+What to check before deploying, newest first. Only releases that need a
+decision or a configuration change appear here; see the
+[CHANGELOG](../../CHANGELOG.md) for everything else.
+
+## To 0.8.0
+
+### Node 20 is the floor
+
+**Who is affected:** anyone installing on Node 18 or older.
+
+`engines` declares `>=20` — the version Debian 13 ships — and the CI runs the
+suite on 20, 22, 24 and 26. Older runtimes are neither tested nor supported.
+
+**`core/auth/llng` is the one plugin that does not follow.** It needs
+`lemonldap-ng-handler`, which depends on the native `re2`, and no single `re2`
+release installs on every supported Node: up to `1.24.0` it builds on 20 but
+not on 26, and from `1.24.1` it declares `engines: >=22`. npm answers an
+unsatisfied dependency of this kind by leaving an _optional_ package out
+without a word, so on some runtimes the handler is simply absent.
+
+Everything else builds, tests and runs there regardless. A server that
+configures `core/auth/llng` on a runtime where the handler could not be
+installed now fails at startup, naming the plugin and the missing package,
+rather than accepting requests an authentication plugin cannot check. Check
+after upgrading that the runtime you deploy on carries it:
+
+```bash
+node -e "require('lemonldap-ng-handler'); console.log('present')"
+```
+
+### The LLNG handler now needs a working configuration at startup
+
+**Who is affected:** every deployment configuring `core/auth/llng`.
+
+The handler used to do nothing at startup: `--llng-ini` was read into the
+configuration but never handed to it, so every request failed with a `500`
+regardless of what the file said. It is now initialized once, before the
+server starts serving — which means the file finally matters, and two ways
+it can be wrong now stop the server instead of answering `500`:
+
+- `--llng-ini` defaults to `/etc/lemonldap-ng/lemonldap-ng.ini`, and a file at
+  that path with no `[node-handler] nodeVhosts` listing this server — the
+  normal state until now, since nothing read it — refuses to start where it
+  used to start and answer `500` to every request instead;
+- an LLNG configuration store (`[configuration] baseConfigUrl` and the rest)
+  unreachable when the server boots crash-loops it under an orchestrator,
+  until the portal or config store it depends on comes up.
+
+List this server before upgrading:
+
+```ini
+[node-handler]
+nodeVhosts = api.example.com
+```
+
+and, if the LLNG configuration store starts after this server does, sequence
+the two or give the container a restart policy that tolerates a few
+failures at boot.
+
+### The Twake schemas now need `core/ldap/enterpriseRules`
+
+**Who is affected:** every deployment loading `static/schemas/twake/*`.
+
+Those schemas mark `twakeDepartmentPath`, `twakeAccountStatus` and
+`twakeDeliveryMode` both `required` and `generated` — a client may not send
+them, and a plugin has to fill them. Load the one that does:
+
+```bash
+--plugin core/ldap/enterpriseRules
+```
+
+Without it, a creation answers `400` naming the attribute, on the flat routes
+as on `POST /ldap/organizations` and `POST /ldap/groups`. That refusal is
+deliberate: the previous release wrote the entry anyway, missing an attribute
+its own schema called required and that no client could ever add.
+
+**The nomenclature has to hold what the schema defaults name.** The user
+schema points at `cn=normal,ou=twakeDeliveryMode,ou=nomenclature,<base>` and
+`cn=active,ou=twakeAccountStatus,ou=nomenclature,<base>`. A directory never
+seeded with those entries answers `400` on every creation, naming the DN that
+does not resolve — rather than storing a dangling one on each account.
+
+### Clients must stop sending the computed attributes
+
+**Who is affected:** anything that creates or updates users, groups or
+organizations against the Twake schemas.
+
+`uid` (generated from the local part of `mail`), `twakeDepartmentPath`,
+`twakeAccountStatus` and `twakeDeliveryMode` are refused in a request body
+with a `400` naming the attribute. Drop them from the payload — the server
+fills them.
+
+To keep the old behaviour, copy the schema and remove the markers: each of
+these is a `generated` or `readOnly` flag in the JSON, not code.
+
+### Run the audit before switching
+
+**Who is affected:** every directory holding entries written before this
+release.
+
+```bash
+npm run audit:directory -- --schema static/schemas/twake/users.json \
+  --plugin core/ldap/enterpriseRules
+```
+
+It reads the branch as it stands and reports what the schema would now refuse,
+quoting each rule's own `hint`. Two rules tightened in ways that only show on
+stored data:
+
+- an array's `items.test` and `items.branch` are enforced on the flat,
+  organization and group routes, where they never were —
+  `mailAlternateAddress` has carried a pattern since 0.7.0 and accepted
+  anything — and an array of pointers must name existing entries;
+- a pointer's `branch` is compared RDN by RDN. A DN that merely ended with the
+  branch as text, `uid=x,xou=users,dc=example,dc=com` against
+  `ou=users,dc=example,dc=com`, used to pass.
+
+Stored values are left alone. The refusal comes at the next update of an
+offending entry, which is why it is worth knowing beforehand.
+
+### `employeeNumber` is unique, apart from the `UNIT` placeholder
+
+**Who is affected:** directories where accounts share a placeholder employee
+number other than `UNIT`.
+
+`static/schemas/twake/users.json` declares `employeeNumber` unique, exempting
+the value `UNIT` — the placeholder the interface these schemas replace uses
+for an account standing for a unit rather than a person. Once
+`core/ldap/enterpriseRules` is loaded, every creation or update carrying a
+value another account already holds answers `409`; `UNIT` is let through
+however many accounts carry it.
+
+A deployment whose placeholder is spelled otherwise has to say so, or its
+second holder of that value is refused, and every existing holder at its next
+update of the attribute. The audit cannot warn: uniqueness spans the whole
+directory, and it only checks what each entry says on its own.
+
+Find the shared values before switching:
+
+```bash
+ldapsearch -LLL -b "ou=users,<base>" "(employeeNumber=*)" employeeNumber \
+  | awk '/^employeeNumber:/ {print $2}' | sort | uniq -cd
+```
+
+Then name yours in a copy of the schema, as
+`static/schemas/example/users.json` does:
+
+```json
+"unique": { "sentinel": "YOUR-PLACEHOLDER" }
+```
+
+### Calendar resource ids, and the branch they are looked for in
+
+**Who is affected:** deployments loading `core/twake/calendar` (the plugin
+`calendarResources` was renamed to).
+
+Three things changed in how an LDAP entry is matched to a Calendar resource.
+A resource whose DN is `cn=…` or `uid=…` directly under the configured base,
+with no escape in its value, keeps the identifier it had and needs nothing.
+
+**`--calendar-resource-base` must be a full DN.** The branch was tested by
+asking whether the DN _contained_ the configured value as text, so a partial
+value like `ou=resources` matched — and matched a sibling branch such as
+`ou=resourcesArchive` with it. It is compared by DN components now, which
+also fixes the other direction: a DN written with spaces after its commas was
+not recognised as a resource at all. Give the option the whole DN; the plugin
+warns at startup when the value is not one under `--ldap-base`.
+
+**The identifier is read from the entry's own RDN.** It used to come from an
+unanchored search for `cn=` or `uid=` anywhere in the DN, so an entry whose
+own RDN was neither borrowed the one of an ancestor; failing that, creation
+fell back to a slug of the entry's name, under which modification and
+deletion then found nothing. An RDN value carrying an escape — `cn=Salle\, 2`
+— was cut at the escape.
+
+So an entry of either of those shapes is now created, patched and deleted in
+Calendar under a different identifier than before. **The resource Calendar
+already holds under the old one is not migrated**: rename it there, or delete
+it and let the next write recreate it. List what is affected before
+upgrading — every resource whose RDN attribute is neither `cn` nor `uid`, and
+every one whose RDN value contains a `\`.
+
+**A modification or a deletion outside the base no longer reaches Calendar.**
+Only creation checked the branch; the other two acted on any entry of the
+entity whose DN yielded an identifier.
+
+### Renaming an entry, and what the cascade reaches
+
+**Who is affected:** anyone calling the new
+`POST /v1/ldap/{resource}/{id}/rename`. Nothing changes for a deployment
+that does not.
+
+The identifier of a flat entry can be changed. The entry's DN changes with
+it, so everything naming that DN has to be rewritten, and the endpoint waits
+for that before it answers.
+
+What it rewrites is read from the schemas, never from a list of attribute
+names: every `pointer` — single or in an array — whose `branch` admits the
+renamed entry, and every attribute carrying the `members` or `owners` role.
+**Load `core/ldap/enterpriseRules`**: without it the entry is renamed and
+nothing else is touched.
+
+What it cannot reach is a DN held in a plain `string` attribute that carries
+no role. Declare it a `pointer`, or give it its role, and it is covered.
+
+A directory running OpenLDAP's `refint` overlay already fixes the attributes
+it is configured for — usually `member`, `owner`, `uniqueMember` and
+`memberOf` — in a task of its own, after the rename has answered. The server
+converges with it rather than fighting it: what the overlay has already
+fixed counts as done. `refint` is not a substitute, though. It never sees a
+deployment's own pointers, `twakeManagerLink` and `twakeLocalAdminLink`
+among them — and losing the second one silently costs an administrator every
+branch they administer.
+
+### A rename answers `207` when it could not finish
+
+The rename of the entry and the rewrite of what points at it are separate
+writes, and a directory has no transaction to hold them together.
+
+If the rename itself fails, nothing else has happened and the directory's own
+refusal is what you get. Once it succeeds the rename is a fact, and an error
+would tell you the opposite — so a rewrite that fails answers `207` with the
+attributes and the counts that could not be written. The referring DNs are
+not in the body, where the caller has no business reading them; they are in
+the log, at `error`, with the attribute and both DNs.
+
+**Re-issue the identical request to finish it.** A rename whose source is
+already gone and whose target is already there runs the rewrite alone. That
+is also what to do if the server dies between the two writes.
+
+### `unique` is not widened on a rename
+
+A schema marking its identifier `unique: { "branches": [...] }` gets the
+RDN's own branch checked on a rename, and nothing more: the wider check runs
+from the add and modify hooks, which a rename does not go through. The
+endpoint's own description says so too.
+
+### Creating an entry that already exists answers `409`
+
+**Who is affected:** any client that reads a failed creation by its status
+code or by the text of its message — a bulk import recording per-line errors
+most of all.
+
+Two creations of the same entry racing past the existence checks answered
+`500`, the add path having wrapped every LDAP error in a plain `Error`. The
+directory's own `entryAlreadyExists` is now recognised once, in
+`lib/ldapActions`, so every creation route answers `409` alike: the flat
+routes, `POST /ldap/groups`, the organization routes, and the external
+members `core/ldap/externalUsersInGroups` inserts.
+
+The message is `Entry <dn> already exists`. The flat routes used to say
+`<entity> <dn> already exists`, and `core/ldap/bulkImport` used to record
+`LDAP add error: …` in its per-line `errors[]`; both read the same now.
+SCIM still answers `uniqueness`, the numeric code being carried on the
+error it is given.
+
+### A flat schema may not claim a URL an LDAP plugin serves
+
+**Who is affected:** anyone passing `--ldap-flat-schema` a schema whose
+`entity.pluralName` is `groups`, `organizations`, `raw` or `bulk-import`
+beside the plugin of the same name — `static/schemas/twake/groups.json` is
+exactly that.
+
+Both used to load, sharing a hook prefix and a URL; Express answered with
+whichever registered first, and the loser stayed advertised by the
+configuration API while being unreachable in fact. The schema is now dropped
+with an error naming the holder. **Load one or the other, not both.**
+
+### Organization paths: nothing to convert
+
+**Who is affected:** directories written before the path order was settled.
+
+`twakeDepartmentPath` reads from the root down, the entry's own name last.
+What is already stored in the old order — the entry's own name first, the top
+organization's last — is still accepted as it stands, so no organization
+becomes unwritable on upgrade. Only paths the server computes from now on
+follow the new order, and the two forms coexist until an entry is rewritten.
+
+### The search cache works now, and is off by default
+
+**Who is affected:** deployments that set `--ldap-cache-ttl` (or
+`DM_LDAP_CACHE_TTL`) explicitly. Everyone else keeps exactly the behaviour
+they had.
+
+The base-scope search cache stored nothing since it was written: the branch
+that would have kept a result could not be reached, so every read went to the
+directory whatever the option said. It caches now — which means a deployment
+that had set the option gets a working cache for the first time, where it used
+to get none.
+
+What a write through this service drops is what it changed, its subtree
+included, whatever case the DN is written in. What this service cannot know
+about, it cannot drop: another replica of it, an LSC synchronisation, a
+hand-run `ldapmodify`. A cached read stays as it was until its TTL runs out.
+
+So `--ldap-cache-ttl` now defaults to `0`, which means no caching at all. Set
+it only where this service is the sole writer of the entries it reads, and
+keep the value under the staleness you are willing to serve.
+
+### `calendarResources` is renamed `calendar`
+
+**Who is affected:** deployments loading `core/twake/calendarResources`, and
+plugins importing `ldap-rest/plugin-twake-calendarresources` or looking the
+plugin up by name.
+
+Besides calendar resources, the plugin propagates user email and name changes
+to the Twake Calendar registered users; the old name hid that. Nothing breaks
+yet: `core/twake/calendarResources` still loads the same plugin, registered
+under its old name, and logs a deprecation warning. It will be removed in a
+future major release, so switch now by **replacing** the old name with the new
+one:
+
+```bash
+# before
+DM_PLUGINS="…,core/twake/calendarResources"
+# after
+DM_PLUGINS="…,core/twake/calendar"
+```
+
+Do not list both: they register under different names, so the loader does not
+see a duplicate and runs two instances — every resource change and every user
+email or name change is then sent to Calendar twice.
+
+Plugin code should import `ldap-rest/plugin-twake-calendar` and look the
+plugin up as `calendar`. Configuration flags (`--calendar-*`) are unchanged.
+
+## To 0.7.0
+
+### `externalId` on Groups is no longer served
+
+**Who is affected:** anyone provisioning Groups from an identity provider and
+reading `externalId` back, or filtering on it.
+
+A Group's `externalId` used to answer its `entryUUID`. RFC 7643 section 3.1
+makes `externalId` the _provisioning client's_ identifier, so the id Okta or
+Entra ID sent was discarded on write, and `filter=externalId eq "<their id>"`
+searched `entryUUID` and matched nothing.
+
+Name an attribute to store it in:
+
+```bash
+--scim-group-external-id-attribute description
+```
+
+Left unset, `externalId` is simply not supported on Groups — absent from
+answers, and refused in filters. That is the honest behaviour; the previous
+one looked like support and was not.
+
+Users are unaffected: theirs was already stored in `employeeNumber`.
+
+**Migrating existing Groups.** Values sent before this release were never
+stored, so there is nothing to convert — re-send them from the provisioning
+side once the flag is set.
+
+### `active` is now writable, and needs an attribute your directory holds
+
+**Who is affected:** every SCIM deployment. Deactivations that used to be
+silently dropped now reach the directory.
+
+`active` is modelled on the presence of one LDAP attribute:
+
+```bash
+--scim-user-lock-attribute pwdAccountLockedTime   # default
+--scim-user-lock-value     000001010000Z          # default, "locked forever"
+```
+
+The default is the ppolicy overlay's convention, and **`pwdAccountLockedTime`
+only exists where slapd loads that overlay**. On a directory without it —
+plain OpenLDAP, 389-ds, AD — a deactivation is refused by the schema and
+answers `400 invalidValue` naming the flags. Point them elsewhere:
+
+```bash
+--scim-user-lock-attribute nsAccountLock
+--scim-user-lock-value     TRUE
+```
+
+Two configuration mistakes are now refused at startup rather than accepted
+and silently ineffective: naming an attribute without a value, and a name
+that is not an LDAP attribute description. Two more are warned about. See
+[the SCIM plugin documentation](plugins/integrations/scim.md#deactivating-an-account-active) for the
+detail.
+
+**Verify once, by hand, that a deactivation actually prevents a bind.**
+Nothing here can check that your directory honours the value you chose:
+`active` is read back from the mere presence of the attribute, so a value the
+directory stores and ignores still reads as `false`.
+
+**One deliberate deviation from RFC 7644 section 3.5.1:** a `PUT` that omits
+`active` leaves the lock as it stands rather than clearing it. Clearing it
+would release locks SCIM never set — a ppolicy auto-lockout after failed
+binds, or one an administrator placed — so a routine profile sync would
+defeat the brute-force control. Send `"active": true` to reactivate
+deliberately.
+
+### `forRequest()` for plugin authors
+
+No action needed to upgrade. If you maintain a plugin that serves HTTP
+requests, `this.server.ldap.forRequest(req)` returns a directory whose methods
+carry the request, so the authorization hooks always see it. The unbound
+methods take the request as a trailing optional argument, and omitting it
+skips every authorization check silently. See the
+[plugin development guide](../plugin-development/README.md#using-ldap-operations).
+
+## To 0.6.2
+
+### Writes that a bypass was letting through are now refused
+
+**Who is affected:** deployments using `core/auth/authzPerBranch` or
+`core/auth/authzLinid1` together with `plugins/ldap/onChange` or
+`plugins/ldap/organizations`.
+
+Both plugins rebuilt the hook tuple without the request, which made every
+authorization plugin registered after them skip its check. Every `modify`,
+and every `rename` for the second, went through unchecked.
+
+**Check your grants before rolling this out widely.** An identity whose
+grants were never quite right may start seeing `403` where it saw `200`. That
+is the fix, not a regression.
+
+Whether a given deployment was exposed was decided by plugin load order,
+which is a race — it could differ from one restart to the next.
+`core/auth/authzDynamic` was never affected: it reads its token from an
+`AsyncLocalStorage` rather than from the request.
+
+## To 0.6.1
+
+### SCIM reads are authorized
+
+**Who is affected:** any SCIM identity granted `write` without `read` on the
+same branch.
+
+Every search the SCIM plugin issued omitted the request, so
+`ldapsearchrequest` — the hook the authorization plugins use — skipped its
+check, and any authenticated identity could read any branch the plugin was
+pointed at.
+
+**An identity that writes now needs `read` on the same branch.** A SCIM write
+answers with the resource it just changed, so it reads the entry back; a
+grant of `write` without `read` no longer serves a write.
+
+`GET /Users`, `GET /Users/{id}` and their Group counterparts answer `403`
+where read is denied.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -56,6 +56,10 @@
       "types": "./dist/src/plugins/auth/authzPerRoute.d.ts",
       "import": "./dist/plugins/auth/authzPerRoute.js"
     },
+    "./plugin-auth-authzscope": {
+      "types": "./dist/src/plugins/auth/authzScope.d.ts",
+      "import": "./dist/plugins/auth/authzScope.js"
+    },
     "./plugin-auth-crowdsec": {
       "types": "./dist/src/plugins/auth/crowdsec.d.ts",
       "import": "./dist/plugins/auth/crowdsec.js"
@@ -96,6 +100,10 @@
       "types": "./dist/src/plugins/demo/helloworld.d.ts",
       "import": "./dist/plugins/demo/helloworld.js"
     },
+    "./plugin-ldap-accountlifecycle": {
+      "types": "./dist/src/plugins/ldap/accountLifecycle.d.ts",
+      "import": "./dist/plugins/ldap/accountLifecycle.js"
+    },
     "./plugin-ldap-bulkimport": {
       "types": "./dist/src/plugins/ldap/bulkImport.d.ts",
       "import": "./dist/plugins/ldap/bulkImport.js"
@@ -104,6 +112,10 @@
       "types": "./dist/src/plugins/ldap/departmentSync.d.ts",
       "import": "./dist/plugins/ldap/departmentSync.js"
     },
+    "./plugin-ldap-enterpriserules": {
+      "types": "./dist/src/plugins/ldap/enterpriseRules.d.ts",
+      "import": "./dist/plugins/ldap/enterpriseRules.js"
+    },
     "./plugin-ldap-externalusersingroups": {
       "types": "./dist/src/plugins/ldap/externalUsersInGroups.d.ts",
       "import": "./dist/plugins/ldap/externalUsersInGroups.js"
@@ -180,6 +192,10 @@
       "types": "./dist/src/plugins/scim/patch.d.ts",
       "import": "./dist/plugins/scim/patch.js"
     },
+    "./plugin-scim-projection": {
+      "types": "./dist/src/plugins/scim/projection.d.ts",
+      "import": "./dist/plugins/scim/projection.js"
+    },
     "./plugin-scim-scim": {
       "types": "./dist/src/plugins/scim/scim.d.ts",
       "import": "./dist/plugins/scim/scim.js"
@@ -204,6 +220,10 @@
       "types": "./dist/src/plugins/twake/appAccountsConsistency.d.ts",
       "import": "./dist/plugins/twake/appAccountsConsistency.js"
     },
+    "./plugin-twake-calendar": {
+      "types": "./dist/src/plugins/twake/calendar.d.ts",
+      "import": "./dist/plugins/twake/calendar.js"
+    },
     "./plugin-twake-calendarresources": {
       "types": "./dist/src/plugins/twake/calendarResources.d.ts",
       "import": "./dist/plugins/twake/calendarResources.js"
@@ -476,6 +496,26 @@
       "import": "./static/schemas/ad/users.json",
       "require": "./static/schemas/ad/users.json"
     },
+    "./schema-example-groups": {
+      "import": "./static/schemas/example/groups.json",
+      "require": "./static/schemas/example/groups.json"
+    },
+    "./schema-example-nomenclature-domains": {
+      "import": "./static/schemas/example/nomenclature/domains.json",
+      "require": "./static/schemas/example/nomenclature/domains.json"
+    },
+    "./schema-example-organizations": {
+      "import": "./static/schemas/example/organizations.json",
+      "require": "./static/schemas/example/organizations.json"
+    },
+    "./schema-example-positions": {
+      "import": "./static/schemas/example/positions.json",
+      "require": "./static/schemas/example/positions.json"
+    },
+    "./schema-example-users": {
+      "import": "./static/schemas/example/users.json",
+      "require": "./static/schemas/example/users.json"
+    },
     "./schema-obm-organizations": {
       "import": "./static/schemas/obm/organizations.json",
       "require": "./static/schemas/obm/organizations.json"
@@ -560,6 +600,10 @@
       "import": "./static/schemas/twake/nomenclature/twakeDeliveryMode.json",
       "require": "./static/schemas/twake/nomenclature/twakeDeliveryMode.json"
     },
+    "./schema-twake-nomenclature-twakedomain": {
+      "import": "./static/schemas/twake/nomenclature/twakeDomain.json",
+      "require": "./static/schemas/twake/nomenclature/twakeDomain.json"
+    },
     "./schema-twake-nomenclature-twakelisttype": {
       "import": "./static/schemas/twake/nomenclature/twakeListType.json",
       "require": "./static/schemas/twake/nomenclature/twakeListType.json"
@@ -603,6 +647,7 @@
     "package.json"
   ],
   "scripts": {
+    "audit:directory": "tsx scripts/audit-directory.ts",
     "build": "npm run build:prod",
     "build:browser": "rollup -c rollup.browser.config.mjs",
     "build:dev": "./.dev.mk builddev",
@@ -611,7 +656,8 @@
     "build:pages": "tsx scripts/build-pages.ts",
     "build:prod": "npm run clean && NODE_ENV=production rollup -c && npm run build:browser && node scripts/moveBrowserLibs.mjs && npm run build:dockerfile",
     "build:watch": "rollup -c --watch",
-    "check": "npm run check:ts && npm run lint && npm run format:check",
+    "check": "npm run check:ts && npm run lint && npm run format:check && npm run check:no-client-values",
+    "check:no-client-values": "sh scripts/check-no-client-values.sh",
     "check:ts": "tsc --noEmit",
     "clean": "rimraf dist/* static/browser/* coverage",
     "coverage": "c8 --config .c8rc.json mocha",
@@ -639,7 +685,7 @@
   },
   "dependencies": {
     "body-parser": "^2.2.0",
-    "csv-parse": "^6.1.0",
+    "csv-parse": "^7.0.2",
     "express": "^5.1.0",
     "express-rate-limit": "^8.1.0",
     "ldapts": "^8.0.9",
@@ -664,7 +710,7 @@
     "@types/supertest": "^6.0.3",
     "@typescript-eslint/eslint-plugin": "^8.44.0",
     "@typescript-eslint/parser": "^8.44.0",
-    "c8": "^10.1.3",
+    "c8": "^12.0.0",
     "chai": "^6.0.1",
     "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",
@@ -674,7 +720,7 @@
     "fast-glob": "^3.3.3",
     "globals": "^14.0.0",
     "js-yaml": "^4.1.1",
-    "mocha": "^11.7.2",
+    "mocha": "^12.0.0",
     "nock": "^14.0.10",
     "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
@@ -691,5 +737,8 @@
     "express-openid-connect": "^2.19.2",
     "lemonldap-ng-handler": "^0.7.3",
     "re2": "^1.22.1"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/static/schemas/example/README.md

@@ -0,0 +1,36 @@
+# Example deployment configuration
+
+These schemas show what a concrete deployment looks like once every
+client-specific value has been moved out of the code: national phone and
+postal-code formats, the mail domain accounts must belong to, the payroll
+number format and the placeholder that exempts a value from its uniqueness
+check, the mailbox quota default, and the naming rules the directory already
+enforces on its existing data.
+
+They are **not** part of the product. Nothing in `src/` refers to them, and the
+`npm run check:no-client-values` guard makes sure nothing ever does. Copy the
+directory, replace the patterns and the domains, and the core serves another
+directory unchanged.
+
+Each `test` carries the `hint` that explains it, so a client can show the
+expected format under the field instead of only rejecting what was typed.
+
+Point a server at them with:
+
+```sh
+node bin/index.mjs \
+  --ldap-base dc=example,dc=org \
+  --ldap-top-organization ou=organization,dc=example,dc=org \
+  --ldap-group-base ou=lists,ou=groups,dc=example,dc=org \
+  --group-schema static/schemas/example/groups.json \
+  --organization-schema static/schemas/example/organizations.json \
+  --ldap-flat-schema static/schemas/example/users.json \
+  --ldap-flat-schema static/schemas/example/positions.json \
+  --ldap-flat-schema static/schemas/example/nomenclature/domains.json \
+  --plugin core/ldap/flatGeneric \
+  --plugin core/ldap/groups \
+  --plugin core/ldap/organizations \
+  --plugin core/ldap/enterpriseRules \
+  --plugin core/ldap/accountLifecycle \
+  --plugin core/auth/authzScope
+```