ldap-rest 1.0.1 → 1.2.0

package/docs/usage/plugins/utilities/static.md

@@ -11,20 +11,30 @@ The `static` plugin serves static files (HTML, CSS, JS, JSON, images) from a dir
 ```bash
 --plugin core/static \
 --static-path ./static \
---static-prefix /static
+--static-name static
 ```
 
 **Environment Variables:**
 
 ```bash
 DM_STATIC_PATH="./static"
-DM_STATIC_PREFIX="/static"
+DM_STATIC_NAME="static"
 ```
 
 ### Parameters
 
 - `--static-path`: Directory containing static files (required)
-- `--static-prefix`: URL prefix for serving files (default: `/static`)
+- `--static-name`: the path the files are served under, without a slash
+  around it (default: `static`, for `/static/…`). Slashes around it are left
+  out and an empty value is `static`; a segment that is empty, `.` or `..`,
+  or that holds what a URL encodes or Express reads as route syntax (a
+  space, a letter outside ASCII, `:`, `*`, `?`, `#`, `%`, brackets, quotes…), stops the server at startup
+- `--static-csp` (`DM_STATIC_CSP`): the `Content-Security-Policy` of the
+  files it serves, default `frame-ancestors 'self'`; `off` sends none. See
+  [Security headers](#security-headers)
+- `--static-frame-options` (`DM_STATIC_FRAME_OPTIONS`): the
+  `X-Frame-Options` of the files it serves, default `SAMEORIGIN`; `off`
+  sends none
 
 ## How It Works
 
@@ -105,7 +115,7 @@ Configuration keys are transformed:
 | `__LDAP_BASE__`             | `--ldap-base`             | `dc=example,dc=com`                 |
 | `__LDAP_TOP_ORGANIZATION__` | `--ldap-top-organization` | `ou=organization,dc=example,dc=com` |
 | `__API_PREFIX__`            | `--api-prefix`            | `/api`                              |
-| `__STATIC_PREFIX__`         | `--static-prefix`         | `/static`                           |
+| `__STATIC_NAME__`           | `--static-name`           | `static`                            |
 
 ## Use Cases
 
@@ -137,17 +147,17 @@ Serve web-based LDAP management interface:
 ```bash
 --plugin core/static \
 --static-path ./static \
---static-prefix /
+--static-name app
 ```
 
 Files:
 
 ```
 ./static/
-  index.html          → http://localhost:8081/
-  css/app.css         → http://localhost:8081/css/app.css
-  js/ldap-tree.js     → http://localhost:8081/js/ldap-tree.js
-  schemas/users.json  → http://localhost:8081/schemas/users.json
+  index.html          → http://localhost:8081/app/
+  css/app.css         → http://localhost:8081/app/css/app.css
+  js/ldap-tree.js     → http://localhost:8081/app/js/ldap-tree.js
+  schemas/users.json  → http://localhost:8081/app/schemas/users.json
 ```
 
 ### 3. API Documentation
@@ -157,7 +167,7 @@ Serve OpenAPI/Swagger documentation:
 ```bash
 --plugin core/static \
 --static-path ./api-docs \
---static-prefix /docs
+--static-name docs
 ```
 
 ```
@@ -172,7 +182,7 @@ GET /docs/swagger-ui/  → ./api-docs/swagger-ui/index.html
 ```bash
 --plugin core/static \
 --static-path ./public \
---static-prefix /static
+--static-name static
 ```
 
 **Directory structure:**
@@ -198,25 +208,17 @@ http://localhost:8081/static/js/app.js
 
 ### Example 2: Root Path Serving
 
-```bash
---plugin core/static \
---static-path ./web \
---static-prefix /
-```
-
-Serves files from root:
-
-```
-http://localhost:8081/index.html
-http://localhost:8081/about.html
-```
+Not supported: the files are always served under `/<static-name>/`, and
+the schema routes, which replace the placeholders, are built on that name.
+To show an application at `/`, have the reverse proxy redirect `/` to it,
+for instance to `/static/index.html`.
 
 ### Example 3: Schema Deployment
 
 ```bash
 --plugin core/static \
 --static-path ./static \
---static-prefix /static \
+--static-name static \
 --ldap-base "dc=example,dc=com"
 ```
 
@@ -240,12 +242,7 @@ http://localhost:8081/about.html
 
 ### Example 4: Multiple Static Plugins
 
-Not directly supported, but you can nest directories:
-
-```bash
---plugin core/static \
---static-path ./static
-```
+One plugin serves several applications from sub-directories:
 
 ```
 ./static/
@@ -257,14 +254,27 @@ Not directly supported, but you can nest directories:
     users.json
 ```
 
-Access via:
-
 ```
 /static/docs/index.html
 /static/app/index.html
 /static/schemas/users.json
 ```
 
+A second directory takes a second instance, loaded under a name of its own
+with its own `static_name` and `static_path`
+([`module:name:{json}`](../auth/README.md#serving-several-populations-from-one-server)):
+
+```bash
+--plugin core/static --static-path ./static \
+--plugin 'core/static:console:{"static_name":"console","static_path":"./console"}'
+```
+
+Give them paths that do not nest: `console` and `console/app` would have the
+first one answer requests meant for the second. The plugins that announce a
+schema URL (groups, organizations, flat entities, SCIM) ask every instance,
+the one registered as `static` first, and leave out one whose path lies under
+an earlier one's, or holds it.
+
 ## Security Considerations
 
 ### Path Traversal
@@ -298,6 +308,43 @@ For restricted access:
 2. Implement custom middleware
 3. Use reverse proxy with access controls
 
+### Security headers
+
+The files served here are applications, an administration console among
+them. So that no other origin frames one signed in (clickjacking), another
+sub-domain or port of the same site included, the responses under the prefix
+carry:
+
+```
+Content-Security-Policy: frame-ancestors 'self'
+X-Frame-Options: SAMEORIGIN
+```
+
+`X-Frame-Options` is for browsers that ignore `frame-ancestors`. A page that
+must be framed by another origin names it:
+
+```bash
+--static-csp "frame-ancestors 'self' https://portal.example.com"
+--static-frame-options off
+```
+
+A full policy can be given the same way, for instance
+`default-src 'self'; frame-ancestors 'none'`, as long as the applications
+served allow it: the policy applies to every file under the prefix. One
+written on several lines, as a YAML block holds it, is sent as one line; a
+value a header cannot hold stops the server at startup. An empty value keeps
+the default, as a compose file expands an unset `${VAR:-}` to one; `off`
+sends no header (`false` in a plugin's JSON override), when the reverse
+proxy sets its own. Keeping both is harmless as long as they agree.
+
+A redirect or a 404 that Express answers itself (a directory without its
+slash, a missing file) carries `Content-Security-Policy: default-src 'none'`
+instead; `X-Frame-Options`, unless set to `off`, still keeps it from being
+framed, and it shows nothing to click.
+
+Every response of the server, API routes included, also carries
+`X-Content-Type-Options: nosniff`, and none says `X-Powered-By: Express`.
+
 ## MIME Types
 
 Express automatically sets Content-Type based on file extension:
@@ -374,9 +421,9 @@ GET /static/index.html → 404
    --static-path ./static
    ```
 
-3. Verify prefix matches URL:
+3. Verify that the name matches the first segment of the URL:
    ```bash
-   --static-prefix /static
+   --static-name static
    ```
 
 ### Problem: Placeholders Not Replaced

package/docs/usage/plugins/utilities/storage.md

@@ -110,6 +110,13 @@ answer "absent" with a warning and writes fail at once instead of waiting.
 does not answer or a package that is not installed; the server starts anyway,
 and every operation tries to connect again.
 
+## Readiness
+
+`GET /readyz` lists the plugin as `degraded` when the backend does not
+answer; the `ldap` backend keeps its records in the directory the probe
+checks on its own, see
+[operations](../../operations.md#what-the-shipped-plugins-report).
+
 ## Expiry
 
 Two rules the backends do not get to reinterpret:

package/docs/usage/plugins/utilities/weblogs.md

@@ -18,6 +18,9 @@ No additional configuration required.
 
 ### Request Logging
 
+Each line carries the `requestId` of the answer's `X-Request-Id`, see
+[operations](../../operations.md#request-id).
+
 Each request is logged when it arrives:
 
 ```
@@ -31,26 +34,31 @@ Each response is logged when completed at **notice** level (between info and war
 ```json
 {
   "level": "notice",
-  "message": "GET /api/v1/ldap/users 200 45ms",
-  "user": "admin",
-  "method": "GET",
-  "url": "/api/v1/ldap/users",
-  "status": 200,
-  "responseTime": "45ms"
+  "message": {
+    "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+    "method": "GET",
+    "url": "/api/v1/ldap/users",
+    "status": 200,
+    "duration": 45,
+    "ip": "10.0.9.12",
+    "user": "admin"
+  },
+  "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+  "timestamp": "2026-10-26T18:07:03.286Z"
 }
 ```
 
 ## Log Fields
 
-| Field          | Description                     | Example                           |
-| -------------- | ------------------------------- | --------------------------------- |
-| `message`      | Summary line                    | `GET /api/v1/ldap/users 200 45ms` |
-| `user`         | Authenticated user (if any)     | `admin`                           |
-| `method`       | HTTP method                     | `GET`, `POST`, `PUT`, `DELETE`    |
-| `url`          | Full URL including query params | `/api/v1/ldap/users?match=*`      |
-| `status`       | HTTP status code                | `200`, `404`, `500`               |
-| `responseTime` | Request duration                | `45ms`, `123ms`                   |
-| `error`        | Error message (if applicable)   | `Connection timeout`              |
+| Field       | Description                     | Example                        |
+| ----------- | ------------------------------- | ------------------------------ |
+| `user`      | Authenticated user (if any)     | `admin`                        |
+| `requestId` | The answer's `X-Request-Id`     | `6effd260-b079-…`              |
+| `method`    | HTTP method                     | `GET`, `POST`, `PUT`, `DELETE` |
+| `url`       | Full URL including query params | `/api/v1/ldap/users?match=*`   |
+| `status`    | HTTP status code                | `200`, `404`, `500`            |
+| `duration`  | Request duration, in ms         | `45`, `123`                    |
+| `error`     | Error message (if applicable)   | `Connection timeout`           |
 
 ## Enriching the Log Line From Another Plugin
 
@@ -77,6 +85,7 @@ Output:
   "level": "notice",
   "message": {
     "uids": ["jdoe", "asmith"],
+    "requestId": "6effd260-b079-4335-b727-544189ed33a6",
     "method": "POST",
     "url": "/api/_getldapentries",
     "status": 200,
@@ -89,7 +98,7 @@ Output:
 
 Notes:
 
-- Core fields (`method`, `url`, `status`, `duration`, `ip`, `user`, `error`)
+- Core fields (`requestId`, `method`, `url`, `status`, `duration`, `ip`, `user`, `error`)
   always take precedence: a plugin cannot overwrite them.
 - The value must be set **before** the response completes (i.e. before
   `res.json()` / `res.end()`), since the entry is written on the `finish` event.
@@ -319,27 +328,40 @@ res.on('close', () => {
 Logs are in JSON format for easy parsing:
 
 ```bash
-cat app.log | jq 'select(.status >= 400)'
+cat app.log | jq 'select(.message.status? >= 400)'
 ```
 
 Filters 4xx and 5xx responses:
 
 ```json
 {
-  "level": "info",
-  "message": "GET /api/v1/ldap/users/notfound 404 12ms",
-  "status": 404,
-  "method": "GET",
-  "url": "/api/v1/ldap/users/notfound"
+  "level": "notice",
+  "message": {
+    "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+    "method": "GET",
+    "url": "/api/v1/ldap/users/notfound",
+    "status": 404,
+    "duration": 12,
+    "ip": "10.0.9.12"
+  },
+  "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+  "timestamp": "2026-10-26T18:07:03.286Z"
 }
 ```
 
+The lines of one request, the access line and what the server logged while
+serving it:
+
+```bash
+cat app.log | jq 'select(.requestId == "6effd260-b079-4335-b727-544189ed33a6")'
+```
+
 ### Statistics
 
 Generate request statistics:
 
 ```bash
-cat app.log | jq -r '.message' | awk '{print $1}' | sort | uniq -c
+cat app.log | jq -r 'select(.message.method?) | .message.method' | sort | uniq -c
 ```
 
 Output:
@@ -356,8 +378,7 @@ Output:
 Average response time per endpoint:
 
 ```bash
-cat app.log | jq -r 'select(.responseTime) | "\(.url) \(.responseTime)"' | \
-  sed 's/ms$//' | \
+cat app.log | jq -r 'select(.message.duration?) | "\(.message.url) \(.message.duration)"' | \
   awk '{sum[$1]+=$2; count[$1]++} END {for (url in sum) print url, sum[url]/count[url] "ms"}'
 ```
 
@@ -377,16 +398,16 @@ For high-traffic deployments:
 
 ## Log Rotation
 
-Configure log rotation using environment or external tools:
+Rotate the log file with external tools:
 
-### Using Winston File Transport
+### Writing to a file
 
 ```bash
---log-file ./logs/ldap-rest.log \
---log-max-size 10485760 \    # 10MB
---log-max-files 5
+--logger file --log-file ./logs/ldap-rest.log
 ```
 
+The server does not rotate the file itself.
+
 ### Using logrotate (Linux)
 
 ```

package/docs/usage/upgrading.md

@@ -4,6 +4,103 @@ 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.
 
+## From 1.1 to 1.2.0
+
+### The process stops on an uncaught exception
+
+**Who is affected:** every deployment; a supervisor, Kubernetes or systemd,
+restarts the process, as it should.
+
+An exception nothing caught was logged and the process kept serving in a
+state nobody knew. The binary now shuts down and exits with 1. On
+`SIGTERM` it also drains what is in flight within `--shutdown-timeout`
+(20 s) and closes its connections before the signal ends it, where the
+signal ended the process at once, the broker connection closed first when
+`core/rabbitmq` was loaded. A host assembling the server in its own
+process gets neither unless it asks: `run()` no longer installs the handlers
+that logged an uncaught exception or an unhandled rejection and kept the
+process alive, so without `exitOnCrash()` or handlers of its own, Node's
+action applies and the process ends on either. See
+[shutdown](operations.md#shutdown).
+
+### The readiness of a pod follows the directory
+
+**Who is affected:** a deployment of the Helm chart, whose probes now call
+`GET /healthz` and `GET /readyz` instead of opening the listen port.
+
+A pod leaves the endpoints while the directory does not answer, where it
+kept receiving requests and answering 500; a rollout started during a
+directory outage waits for the directory. Both routes are served without
+authentication: an Ingress routing `/` exposes them, keep the two paths to
+the cluster. See [operations](operations.md#health-and-readiness).
+
+### `--ldap-dn` and `--ldap-pwd` are required
+
+**Who is affected:** a deployment that left one of them unset, and so bound
+as `cn=admin,dc=example,dc=com` or with the password `admin`; the published
+Docker image carried both in its `ENV`, and the Helm chart's example only set
+the password.
+
+The server now stops at startup naming the missing option. Set `DM_LDAP_DN`
+and `DM_LDAP_PWD` (or `--ldap-dn` and `--ldap-pwd`) to the values that were
+implied.
+
+### Every entity route checks the shape of a value
+
+**Who is affected:** a script or connector writing through `/api/v1/ldap/<entity>`,
+`/api/v1/ldap/groups` or `/api/v1/ldap/organizations` text that is not a
+number for a `number` or `integer`, a `delete` of a `required` attribute as
+a whole, or a change naming an attribute a strict schema does not declare;
+one writing through `/api/v1/ldap/<entity>` several values for an attribute
+the schema does not type `array`; and one changing a `fixed` attribute of a
+group, which the server dropped from the change and answered 200. The
+server now answers 400, naming the attribute. A group creation sending a
+value under a `fixed` attribute now writes the schema's default, or the
+value when the schema gives none, where it wrote nothing. The shipped LSC connector sends shapes that stay
+accepted, a list of one in a `replace` and one value for an `array` on a
+creation; its whole-attribute delete is refused for a `required` attribute,
+as any, and a group synchronisation that forces `objectClass` or another
+`fixed` attribute now has the whole update refused: keep those attributes
+out of the group updates.
+
+Send one value for a single-valued attribute, a list for an `array` (one
+value, or a list of one, is taken either way), numbers as numbers or digits,
+and `null` or `[]` in a `replace` to clear an attribute. The rules are in
+[what a value must look like](../client-development/schemas/README.md#what-a-value-must-look-like).
+
+### `--logger`: `console` or `file`
+
+A `DM_LOGGER` set to anything else wrote `error.log` in the working
+directory; the server now stops at startup. Set `DM_LOGGER=file` to keep
+that file, and `DM_LOG_FILE` to name another one. An empty `DM_LOGGER` is
+`console`.
+
+## From 1.0 to 1.1.0
+
+### The static files can no longer be framed by another origin
+
+`core/static` sends `Content-Security-Policy: frame-ancestors 'self'` and
+`X-Frame-Options: SAMEORIGIN`. A page of another origin, another sub-domain
+or port of the same site included, that showed one of its applications in an
+`<iframe>`, a portal for instance, now shows an empty frame. Name it:
+
+```bash
+--static-csp "frame-ancestors 'self' https://portal.example.com"
+--static-frame-options off
+```
+
+See [security headers](plugins/utilities/static.md#security-headers).
+
+### `--static-name`: an empty value is `static`
+
+With `DM_STATIC_NAME=` the files were served at the root while the
+configuration API and SCIM announced `/static`; they are now served under
+`/static`. Slashes around the name are left out (`/static/` is `static`). A
+name Express would not match as written, with an empty, `.` or `..` segment,
+or what a URL encodes or Express reads as route syntax in it (a space, a
+letter outside ASCII, `:`, `*`, `?`, `#`, `%`, brackets, quotes…), stops
+the server at startup.
+
 ## From 0.26 to 1.0.0
 
 Every breaking change since 0.26.0. Authorization fails closed in 1.0.0:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -160,6 +160,10 @@
       "types": "./dist/src/plugins/ldap/trash.d.ts",
       "import": "./dist/plugins/ldap/trash.js"
     },
+    "./plugin-metrics": {
+      "types": "./dist/src/plugins/metrics.d.ts",
+      "import": "./dist/plugins/metrics.js"
+    },
     "./plugin-rabbitmq": {
       "types": "./dist/src/plugins/rabbitmq.d.ts",
       "import": "./dist/plugins/rabbitmq.js"
@@ -288,6 +292,10 @@
       "types": "./dist/src/plugins/twake/lifecycleEvents.d.ts",
       "import": "./dist/plugins/twake/lifecycleEvents.js"
     },
+    "./plugin-twake-migrationproxy": {
+      "types": "./dist/src/plugins/twake/migrationProxy.d.ts",
+      "import": "./dist/plugins/twake/migrationProxy.js"
+    },
     "./plugin-twake-spaces": {
       "types": "./dist/src/plugins/twake/spaces.d.ts",
       "import": "./dist/plugins/twake/spaces.js"
@@ -754,6 +762,7 @@
     "multer": "^2.0.2",
     "node-fetch": "^3.3.2",
     "p-limit": "^7.1.1",
+    "prom-client": "^15.1.3",
     "winston": "^3.17.0"
   },
   "devDependencies": {
@@ -795,7 +804,7 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@linagora/rabbitmq-client": "^0.1.2",
+    "@linagora/rabbitmq-client": "^0.7.2",
     "express-openid-connect": "^2.19.2",
     "iovalkey": "^0.4.0",
     "lemonldap-ng-handler": "^0.7.3",

package/static/schemas/example/README.md

@@ -20,6 +20,7 @@ Point a server at them with:
 ```sh
 node bin/index.mjs \
   --ldap-base dc=example,dc=org \
+  --ldap-dn cn=admin,dc=example,dc=org --ldap-pwd secret \
   --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 \