ldap-rest 1.2.1 → 2.0.0

package/docs/usage/configuration.md

@@ -149,6 +149,11 @@ of the environment variable. An empty value on the command line, such as an
 unset variable expanding to nothing, stops the server: leave the option out
 to keep the default.
 
+An option or `DM_*` variable that no declared option reads is named in a
+warning at startup. `--strict-options` refuses it instead. Kubernetes injects
+`DM_*` variables for services whose name starts with `dm`; leave the flag off
+where those names are in use.
+
 ## General Options
 
 | CLI                  | Plural           | Env                   | Default          | Description                                                                                       |
@@ -160,6 +165,7 @@ to keep the default.
 | `--logger`           |                  | `DM_LOGGER`           | `console`        | `console` or `file`, see [Logger](#logger---logger)                                               |
 | `--log-file`         |                  | `DM_LOG_FILE`         | `error.log`      | File `--logger file` writes to                                                                    |
 | `--debug`            |                  | `DM_DEBUG`            | `false`          | Name the failure in the 5xx answers of the error middleware and `serverError`; not for production |
+| `--strict-options`   |                  | `DM_STRICT_OPTIONS`   | `false`          | Refuse an option or `DM_*` variable no declared option reads                                      |
 | `--api-prefix`       |                  | `DM_API_PREFIX`       | `/api`           | API URL prefix                                                                                    |
 | `--mail-domain`      | `--mail-domains` | `DM_MAIL_DOMAIN`      | `[]`             | Mail domains                                                                                      |
 | `--schemas-path`     |                  | `DM_SCHEMAS_PATH`     | `static/schemas` | Path to JSON schemas                                                                              |
@@ -229,15 +235,15 @@ at `0` otherwise.
 
 #### `core/ldap/groups`
 
-| CLI                                | Plural            | Env                             | Default                            | Description                 |
-| ---------------------------------- | ----------------- | ------------------------------- | ---------------------------------- | --------------------------- |
-| `--ldap-group-base`                |                   | `DM_LDAP_GROUP_BASE`            |                                    | Groups base DN              |
-| `--ldap-groups-main-attribute`     |                   | `DM_LDAP_GROUPS_MAIN_ATTRIBUTE` | `cn`                               | Group identifier attribute  |
-| `--group-class`                    | `--group-classes` | `DM_GROUP_CLASSES`              | `top,groupOfNames`                 | Group objectClasses         |
-| `--group-allow-unexistent-members` |                   | `DM_ALLOW_UNEXISTENT_MEMBERS`   | `false`                            | Allow non-existent members  |
-| `--group-default-attributes`       |                   | `DM_GROUP_DEFAULT_ATTRIBUTES`   | `{}`                               | Default attributes (JSON)   |
-| `--group-dummy-user`               |                   | `DM_GROUP_DUMMY_USER`           | `cn=fakeuser`                      | Dummy user for empty groups |
-| `--group-schema`                   |                   | `DM_GROUP_SCHEMA`               | `static/schemas/twake/groups.json` | Group JSON schema path      |
+| CLI                                 | Plural            | Env                             | Default                            | Description                 |
+| ----------------------------------- | ----------------- | ------------------------------- | ---------------------------------- | --------------------------- |
+| `--ldap-group-base`                 |                   | `DM_LDAP_GROUP_BASE`            |                                    | Groups base DN              |
+| `--ldap-groups-main-attribute`      |                   | `DM_LDAP_GROUPS_MAIN_ATTRIBUTE` | `cn`                               | Group identifier attribute  |
+| `--group-class`                     | `--group-classes` | `DM_GROUP_CLASSES`              | `top,groupOfNames`                 | Group objectClasses         |
+| `--groups-allow-unexistent-members` |                   | `DM_ALLOW_UNEXISTENT_MEMBERS`   | `false`                            | Allow non-existent members  |
+| `--group-default-attributes`        |                   | `DM_GROUP_DEFAULT_ATTRIBUTES`   | `{}`                               | Default attributes (JSON)   |
+| `--group-dummy-user`                |                   | `DM_GROUP_DUMMY_USER`           | `cn=fakeuser`                      | Dummy user for empty groups |
+| `--group-schema`                    |                   | `DM_GROUP_SCHEMA`               | `static/schemas/twake/groups.json` | Group JSON schema path      |
 
 #### `core/ldap/externalUsersInGroups`
 
@@ -429,6 +435,7 @@ whichever of the two names it selects. A value other than `req.user` or
 | ---------------------------------- | ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--authz-per-branch-config`        | `DM_AUTHZ_PER_BRANCH_CONFIG`        | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                                                                                                                                                                                     |
 | `--authz-per-branch-cache-ttl`     | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`     | `60`                                             | Cache TTL (seconds)                                                                                                                                                                                                                                                                                                                             |
+| `--ldap-group-member-attribute`    | `DM_LDAP_GROUP_MEMBER_ATTRIBUTE`    | `member`                                         | Attribute a group lists its members in                                                                                                                                                                                                                                                                                                          |
 | `--authz-filter-attached-entries`  | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES`  | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch`; always on under `authzLinid1`; does nothing under `authzDynamic`.                                                                                                                                                      |
 | `--authz-transit-branch`           | `DM_AUTHZ_TRANSIT_BRANCH`           |                                                  | Organization entries are handed over through when they are judged by attachment: every administrator sees and may claim what is there, and puts an entry there with write on the organization it leaves. An entry attached to no organization is in transit too. See [authzLinid1](plugins/auth/authz-linid1.md#transit-handing-an-entry-over). |
 | `--authz-transit-origin-attribute` | `DM_AUTHZ_TRANSIT_ORIGIN_ATTRIBUTE` |                                                  | Attribute an entry put in transit keeps the organization it leaves in, removed when it is claimed. Empty records nothing; it must exist in the directory's schema. See [authzLinid1](plugins/auth/authz-linid1.md#where-an-entry-comes-from).                                                                                                   |
@@ -523,7 +530,7 @@ Formerly `core/twake/calendarResources`, still accepted as a deprecated alias.
 | `--calendar-concurrency`          | `DM_CALENDAR_CONCURRENCY`          | `10`                    | API concurrency               |
 | `--calendar-resource-base`        | `DM_CALENDAR_RESOURCE_BASE`        |                         | Resource base DN              |
 | `--calendar-resource-objectclass` | `DM_CALENDAR_RESOURCE_OBJECTCLASS` |                         | Resource objectClass          |
-| `--calendar-resource-creator`     | `DM_CALENDAR_RESOURCE_CREATOR`     |                         | Resource creator              |
+| `--calendar-resource-creator`     | `DM_CALENDAR_RESOURCE_CREATOR`     | `admin@example.com`     | Resource creator              |
 | `--calendar-resource-domain`      | `DM_CALENDAR_RESOURCE_DOMAIN`      |                         | Resource domain               |
 | `--calendar-firstname-attribute`  | `DM_CALENDAR_FIRSTNAME_ATTRIBUTE`  | `givenName`             | Registered user first name    |
 | `--calendar-lastname-attribute`   | `DM_CALENDAR_LASTNAME_ATTRIBUTE`   | `sn`                    | Registered user last name     |
@@ -722,7 +729,7 @@ see [Storage](plugins/utilities/storage.md).
 
 #### `core/configApi`
 
-Exposes API configuration at `/api/v1/config` for client applications. Returns available features, schemas, and endpoints. No configuration options.
+Exposes API configuration at `/api/v1/config` for client applications. Returns available features, schemas, endpoints, and the server's `version` — read from the `package.json` that ships with it, so a client can tell an administrator the server is older than it supports. No configuration options.
 
 ## Configuration File
 

package/docs/usage/operations.md

@@ -41,7 +41,26 @@ and `/readyz` names the loaded plugins that report: on an ingress exposing
 the server to the internet, keep the two paths to the cluster.
 
 The Helm chart probes both routes over HTTP (`livenessProbe` and
-`readinessProbe` in `values.yaml`).
+`readinessProbe` in `values.yaml`). The published image also declares a
+`HEALTHCHECK` calling `GET /healthz` from inside the container, on `DM_PORT`:
+`docker ps` reports the container unhealthy when it stops answering, and a
+`--restart` policy restarts it as it would after a crash, while an
+orchestrator with probes of its own ignores the declaration. A port given
+any other way (`--port` in a configuration file, a plugin) leaves the check
+on 8081.
+
+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. 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
 
@@ -110,6 +129,7 @@ the rate limiting and the request id, to keep to the cluster or the host.
 | `ldap_rest_ldap_pool_wait_seconds`            | histogram |                             | Time to get a pooled connection, opening one included                                                                                                                                                                                                                                                           |
 | `ldap_rest_ldap_pool_connections`             | gauge     | `state`                     | Pooled connections, `busy` or `idle`                                                                                                                                                                                                                                                                            |
 | `ldap_rest_ldap_pool_waiting`                 | gauge     |                             | Operations waiting for a connection, the pool being full                                                                                                                                                                                                                                                        |
+| `ldap_rest_ldap_pool_opening`                 | gauge     |                             | Connections being opened, within `--ldap-pool-size`                                                                                                                                                                                                                                                             |
 | `ldap_rest_ldap_pool_max`                     | gauge     |                             | `--ldap-pool-size`                                                                                                                                                                                                                                                                                              |
 | `ldap_rest_ldap_search_cache_total`           | counter   | `result`                    | Cacheable searches, `hit` or `miss`; nothing when the cache is off                                                                                                                                                                                                                                              |
 | `ldap_rest_hook_failures_total`               | counter   | `hook`, `plugin`            | Notification hooks (`*done`, `onLdap*`) that threw, which the server logs and goes on                                                                                                                                                                                                                           |
@@ -117,6 +137,10 @@ the rate limiting and the request id, to keep to the cluster or the host.
 | `ldap_rest_unhandled_rejections_total`        | counter   |                             | Promise rejections nothing handled; counted by the binary, a host skipping `exitOnCrash()` leaves it at zero                                                                                                                                                                                                    |
 | `process_*`, `nodejs_*`                       |           |                             | The process: CPU, memory, event loop lag, handles, GC                                                                                                                                                                                                                                                           |
 
+A burst of requests that has to open connections no longer opens one per
+request: a connection being opened takes its place in the pool, and the
+requests over `--ldap-pool-size` wait for a free one.
+
 A search the caller pages is timed page by page, what the caller does
 between two pages left out; the readiness ping is not timed. The route
 label is the template a route was declared with, never the URL: a label
@@ -128,9 +152,9 @@ James's does, is a call like another. A plugin calling a service through
 `this.fetch` has its calls counted under its name; the OpenID Connect
 client's calls to its provider are made by its library, and not timed.
 
-The instruments come from `prom-client` 15, kept while the server supports
-Node 20, which its successor `@prometheus-io/client` dropped: the
-deprecation notice `npm install` prints is expected.
+The instruments come from `prom-client` 15, which `npm install` reports as
+deprecated: its successor `@prometheus-io/client` is the migration to make,
+and the notice is expected until it is done.
 
 The port listens on every interface. What to alert on: `/readyz` for a
 replica out of rotation, `result="error"` in

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/enterprise-rules.md

@@ -119,7 +119,10 @@ whenever the link changes. Mark the path `generated` so a client cannot set it.
 
 `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.
+applies to creations and to updates. A size above 2⁵³ − 1 bytes is refused
+(400), since its number of bytes would be rounded. A schema `number` or
+`integer` refuses a whole number beyond 2⁵³ on its own, whatever the type;
+see [what a value must look like](../../../client-development/schemas/README.md#what-a-value-must-look-like).
 
 ### Server-owned defaults
 
@@ -144,6 +147,12 @@ 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.
 
+The date is an LDAP generalized time, read as written: the year keeps its
+four digits (`0029123123` is a date of year 29, not 1929), and a leap second
+(`20991231235960Z`) is the instant that follows the day. The zone is `Z` or a
+difference of hours and minutes from UTC (`+00`, `+02`, `-0530`, `+14:00`); a
+value past 23 hours or 59 minutes is answered 400 as invalid.
+
 ### Deletion and references
 
 ```json

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

@@ -451,6 +451,17 @@ 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. 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
 
 ```bash

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

@@ -157,7 +157,10 @@ POST /api/v1/ldap/groups
 
 **Notes:**
 
-- `cn` is required
+- `cn` is required; it is a name, or the group's DN in the groups branch,
+  whose first RDN gives the name, folded as the directory folds it. The DN
+  form follows the same
+  [escape rule as a flat entity's identifier](flat-generic.md#create-entry)
 - `member` can be a string (single member) or array (multiple members)
 - If no members provided, a dummy member is automatically added, and it is
   left out of `member` when the group is read back, on both the list and the

package/docs/usage/plugins/ldap/password-policy.md

@@ -155,6 +155,10 @@ curl "http://localhost:8081/api/v1/users/uid%3Djohn.doe%2Cou%3Dusers%2Cdc%3Dexam
 }
 ```
 
+A `pwdMaxAge` large enough to put the expiry beyond the representable date
+range is reported as no expiry: `expiresAt` and `daysUntilExpiration` are
+`null`, and `isExpired` stays `false`.
+
 ### Unlock User Account
 
 ```http
@@ -337,6 +341,9 @@ curl -X PATCH "http://localhost:8081/api/v1/password-policies/default" \
 
 - `pwdAttribute` and `pwdCheckModule` are read-only. Before OpenLDAP 2.6,
   `pwdCheckModule` is the path of a library slapd loads; set it in slapd.
+- Durations and counts are integers from 0 to 9007199254740991 (2⁵³ − 1),
+  the largest a JSON number holds exactly: a larger value, or one sent as an
+  exponent such as `1e21`, is refused with a `400`.
 - `pwdCheckModuleArg`, the configuration of the quality-check module (ppm,
   for instance), is a string, usually of several lines. Writing it, or
   `pwdUseCheckModule`, gives the entry the `pwdPolicyChecker` class. Both

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

@@ -181,6 +181,22 @@ Site-specific attributes are added with `--ldap-raw-hidden-attribute`, which sta
 --ldap-raw-hidden-attribute twakeApiKey --ldap-raw-hidden-attribute employeeNumber
 ```
 
+A hidden attribute is resolved to its directory type, so the type's OID and
+every alias it declares are hidden too — asking for `2.5.4.35` or
+`homePhone` does not serve `userPassword` or a configured
+`homeTelephoneNumber`. A search filter that tests a hidden type, at any
+depth and under any of its names, is refused with a 400: the search runs with
+the service account's rights, so leaving it through would answer the same
+question one match at a time. An assertion on a supertype of a hidden type is
+refused as well, since the directory evaluates an attribute's subtypes. An
+extensible match without an attribute (`(:octetStringMatch:=…)`) runs over
+every attribute and is refused too while attributes are hidden.
+
+When the directory schema cannot be read, an entry read or a search is
+refused with a 503 rather than answered with only the configured names
+compared, which could serve an alias or an OID. The root DSE still answers:
+it carries no entry values and is how a client discovers the schema.
+
 Note that hiding an attribute here keeps it out of the API, not out of the directory: an account able to bind to LDAP directly still reads it. This is a guard against casual exposure through the browsing UI, not an access control — use [authz-per-branch](../auth/authz-per-branch.md) or directory ACLs for that.
 
 ## Security
@@ -189,7 +205,7 @@ Access is restricted in three independent layers:
 
 1. **Exposed bases** — any DN outside `--ldap-raw-base` is refused with a 403, whatever the caller's rights.
 2. **Authorization hooks** — every entry read, children listing and search goes through `server.ldap`, so the authorization plugins ([authz-per-branch](../auth/authz-per-branch.md), authz-dynamic, …) apply exactly as on the high-level APIs.
-3. **Hidden attributes** — credential attributes, plus anything in `--ldap-raw-hidden-attribute`, are removed from every response, including searches. See [Hidden attributes](#hidden-attributes).
+3. **Hidden attributes** — credential attributes, plus anything in `--ldap-raw-hidden-attribute`, are removed from every response, including searches, under every name their type answers to; a filter that tests one is refused with a 400. See [Hidden attributes](#hidden-attributes).
 
 Two exceptions, both deliberate: the **root DSE** and the **schema** are read with the service account, not with the caller's rights. They are directory metadata and carry no user data; reading them with a restricted account would leave the UI unable to name and type attributes. Do not expose this plugin publicly if your directory publishes sensitive information in its root DSE.