ldap-rest 0.26.0 → 1.0.0

package/dist/src/plugins/ldap/organizations.d.ts

@@ -219,7 +219,8 @@ export default class LdapOrganizations extends DmPlugin {
      * search just learned to survive: a directory that will not walk the whole
      * link filter is told about rather than turned into an empty list.
      *
-     * @param baseDn branch the attached entries live in
+     * @param baseDn branch the attached entries live in; the organization's
+     *        own, for a caller who may not search it
      * @param filter what links them to the organization
      * @param cap how many to return
      * @param dn organization they are attached to, for the indicator's DN
@@ -253,9 +254,8 @@ export default class LdapOrganizations extends DmPlugin {
      * The same two searches as `getOrganisationSubnodes`, narrowed by a query.
      *
      * Both go through the helpers that classify a failure rather than reading
-     * every one of them as emptiness (#179), and both now carry the request:
-     * they ran without one, and an authorization plugin skips its check when
-     * there is none — the same gap the flat routes had until 0.8.2. The
+     * every one of them as emptiness (#179), and both carry the request the
+     * authorization plugins judge them by. The
      * attached entries are capped like the other endpoint's, since an answer
      * the directory refuses to finish is what this is about.
      *

package/dist/src/plugins/twake/appAccountsApi.d.ts

@@ -1,71 +1,6 @@
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
-/**
- * @openapi-component
- * AppAccount:
- *   type: object
- *   description: |
- *     An application-specific identity attached to a user.  App accounts
- *     allow a single principal user to authenticate as different named
- *     "devices" or "applications" each with its own credential, while
- *     sharing the same mail address.
- *   required: [uid]
- *   properties:
- *     uid:
- *       type: string
- *       description: |
- *         Unique identifier of the app account.  Format:
- *         `<prefix>_c<8-digits>`, where `<prefix>` is the `:user` path param
- *         (the resolution value — the mail by default) sanitized into a
- *         uid-safe token (e.g. `alice@example.com` -> `alice_example_com`).
- *       example: alice_example_com_c04729183
- *     name:
- *       type: string
- *       description: Human-readable label (stored as LDAP `description`).
- *       example: Work laptop
- *   example:
- *     uid: alice_c04729183
- *     name: Work laptop
- * AppAccountCreated:
- *   type: object
- *   description: |
- *     Response returned when a new app account is successfully created.
- *     The one-time cleartext password is included here and never returned
- *     again — callers must store it immediately.
- *   required: [uid, pwd, mail]
- *   properties:
- *     uid:
- *       type: string
- *       description: Identifier of the newly created app account.
- *       example: alice_c04729183
- *     pwd:
- *       type: string
- *       description: |
- *         One-time cleartext password generated for this account.
- *         Format: 6 blocks of 4 characters separated by `-`
- *         (e.g. `Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@`).
- *         OpenLDAP hashes it via ppolicy before storage.
- *       example: Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@
- *     mail:
- *       type: string
- *       description: Mail address of the principal account this app account belongs to.
- *       example: alice@example.com
- *   example:
- *     uid: alice_c04729183
- *     pwd: Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@
- *     mail: alice@example.com
- * AppAccountCreate:
- *   type: object
- *   description: Request body for creating a new app account.
- *   properties:
- *     name:
- *       type: string
- *       description: Optional human-readable label for the new account.
- *       example: Work laptop
- *   example:
- *     name: Work laptop
- */
 export default class AppAccountsApi extends DmPlugin {
     name: string;
     roles: Role[];
@@ -87,8 +22,9 @@ export default class AppAccountsApi extends DmPlugin {
      * `:user` is matched against the configured resolution attribute
      * (`app_accounts_user_attribute`, default the mail attribute). Mail is
      * globally unique; resolving by the LDAP `uid` instead is only safe when uid
-     * is unique directory-wide, as the same `uid` may repeat under different
-     * subtrees and resolve to an arbitrary same-named user (see #88).
+     * is unique directory-wide: a `uid` repeated under different subtrees is
+     * answered 409 when the caller reads several of its holders, and resolves
+     * to the one it reads otherwise (see #88).
      *
      * On failure (no match, or an ambiguous one) this writes the HTTP error
      * response and returns null, so callers can simply `return` when it does.

package/dist/src/plugins/twake/groups.d.ts

@@ -81,6 +81,40 @@ export default class TwakeGroups extends LdapGroups {
      * SCIM group mapping leaves the RDN attribute alone.
      */
     afterLoad(): void;
+    /**
+     * A group of `org` with its organization link, under an authorization
+     * model judging entries by that link (`authzLinid1`,
+     * `--authz-filter-attached-entries`): there, a group without one is every
+     * administrator's. Elsewhere the group is left as it is, and judged by its
+     * branch as before.
+     *
+     * The auxiliary class `twakeGroup` is added when the group holds neither
+     * it nor `twakeStaticGroup`. A link the writer gave is kept when it names
+     * the group's organization, refused otherwise: a group in one
+     * organization's branch belonging to another would mix their members.
+     *
+     * @param dn the group's DN
+     * @param org its organization
+     * @param entry the group as written
+     * @returns the group, linked
+     * @throws BadRequestError when the link given names another organization
+     */
+    linked(dn: string, org: string, entry: AttributesList): AttributesList;
+    /**
+     * Refuse a change taking a group's link away from its organization, under
+     * a model judging by attachment: as on a creation, a group in one
+     * organization's branch cannot belong to another, nor to none.
+     *
+     * @param dn the group's DN
+     * @param changes the modification
+     * @throws BadRequestError when the change links it elsewhere or unlinks it
+     */
+    private checkLinkChange;
+    /**
+     * Whether an authorization plugin judges entries by their organization
+     * link: then a group needs one.
+     */
+    private judgedByAttachment;
     /** The organization a group DN belongs to, if it is a group at all. */
     organizationOf(dn: string): string | undefined;
     groupBaseOf(org: string): string;
@@ -112,14 +146,24 @@ export default class TwakeGroups extends LdapGroups {
     groupDn(org: string, id: string): string;
     get userAttribute(): string;
     userDn(org: string, username: string): string;
-    /** Every route answers 404 for a missing organization, 410 for a deleted one. */
-    checkOrganization(org: string): Promise<void>;
+    /**
+     * Every route answers 404 for a missing organization, 410 for a deleted one.
+     *
+     * The status is read as the server, whoever asks; an organization the
+     * caller of `req` cannot read answers as one that is not there, deleted or
+     * not.
+     */
+    checkOrganization(org: string, req?: Request): Promise<void>;
     /** Page, search and sort of a list route, or a refusal of them. */
     page(req: Request, sortable: string[]): Page;
     sorted<T extends Record<string, unknown>>(items: T[], sortBy: string | undefined, desc: boolean): T[];
     /** A group as the routes answer it: members named by their RDN value. */
     groupOf(org: string, entry: AttributesList): Record<string, unknown>;
     groups(org: string, filter: string, attributes?: string[], req?: Request): Promise<AttributesList[]>;
+    /**
+     * A group, read as the caller of `req` when there is one: a group they
+     * cannot read answers as one that is not there.
+     */
     private readGroup;
     /** The group of that display name in the organization, if any. */
     private named;

package/dist/src/plugins/twake/james.d.ts

@@ -37,17 +37,6 @@ export default class James extends TwakePlugin {
      */
     private getUserQuota;
     hooks: Hooks;
-    /**
-     * Where the mail domain entries live, and the attribute naming their
-     * domain: each loaded flat schema declaring the `domainName` role, the
-     * lookup `core/ldap/enterpriseRules` makes. Without one, the branch of the
-     * shipped `twake/nomenclature/twakeDomain.json` and the attribute
-     * `--enterprise-domain-name-attribute` names.
-     *
-     * Rebuilt on each call, as the enterprise rules do theirs: a list taken in
-     * the constructor could predate the schemas.
-     */
-    private domainBranches;
     /**
      * The attribute naming the mail domain of the entry at a DN, when it lies
      * in a domain branch: at any depth, as a deployment may nest its domains

package/docs/README.md

@@ -32,6 +32,31 @@ Integrate LDAP-Rest into your web applications.
 - **[JSON Schemas](client-development/schemas/README.md)** - Schema structure and validation
 - **[Examples](client-development/examples/README.md)** - React, Vue.js, Vanilla JS integration
 
+## API stability
+
+From 1.0.0, ldap-rest follows semantic versioning. These are its public
+API, which a minor or a patch release does not break:
+
+- **Configuration**: the options and environment variables of
+  [Configuration](usage/configuration.md) and of each plugin's page.
+- **Routes**: the paths, bodies and answers of the
+  [REST API](client-development/api/rest-api.md) and the plugin pages,
+  their statuses and their error `code`s.
+- **Plugin API**: what `ldap-rest/plugin` exports — `DmPlugin` and its
+  roles (`auth`, `authz`, …), `asyncHandler`, the DN and filter escaping
+  helpers and the error classes —, the `DM` type of `ldap-rest` and the
+  `Hooks` of `ldap-rest/hooks`, whose arguments are those typed in
+  `src/hooks.ts` ([hooks](plugin-development/hooks.md)), and the directory
+  operations of [the development guide](plugin-development/README.md):
+  `ldap.search`, `add`, `modify`, `rename`, `delete`, `ldap.forRequest`,
+  `ldap.system`, `ldap.authorize`, `ldap.readableBy`,
+  `ldap.canonicalAttributes`, `ldap.canonicalChanges` and
+  `ldap.knowAttributeNames`.
+- **Schemas**: the JSON schema format and the shipped schemas' attributes.
+
+Everything else — other exports, internal helpers, log messages — may
+change in any release.
+
 ## Presentations
 
 Interactive presentations (using [presenterm](https://github.com/mfontanini/presenterm)):

package/docs/plugin-development/README.md

@@ -455,14 +455,13 @@ export default class MyPlugin extends DmPlugin {
 
 The `this.server.ldap` object provides access to all LDAP operations:
 
-> **Serving an HTTP request? Bind it first.**
+> **Say whose each operation is.**
 >
 > The authorization plugins (`core/auth/authzPerBranch`,
 > `core/auth/authzDynamic`, …) hook `ldapsearchrequest`, `ldapaddrequest`,
-> `ldapmodifyrequest`, `ldaprenamerequest` and `ldapdeleterequest`, and they
-> **skip every check when the request is missing**. The methods below take it as a trailing
-> optional argument, so forgetting it does not fail — it silently authorizes
-> the operation. Three such bugs shipped in the SCIM plugin.
+> `ldapmodifyrequest`, `ldaprenamerequest` and `ldapdeleterequest`, and judge
+> an operation by the request it carries. The methods below take it as a
+> trailing optional argument.
 >
 > In a request handler, bind once and use the result:
 >
@@ -472,21 +471,50 @@ The `this.server.ldap` object provides access to all LDAP operations:
 > await directory.modify(dn, changes);
 > ```
 >
-> `forRequest()` returns a `RequestBoundLdap`, whose methods have no request
-> parameter at all — the omission stops being expressible. Use the unbound
-> methods only for work that genuinely belongs to no request, such as startup
-> or scheduled tasks, where passing nothing is the deliberate answer — and
-> say so by reaching for them through `ldap.system`:
+> An operation that names no request while an authenticated request is being
+> served is made for that request all the same, and judged as its caller: a
+> forgotten argument fails closed. Work that is the server's — a uniqueness
+> check has to see a whole branch, and a reference to an entry the caller
+> cannot read is still a valid reference — goes through `ldap.system`, which
+> steps out of the request, with a comment saying why:
 >
 > ```typescript
+> // As the server: a name is taken whoever may read the entry holding it
 > await this.server.ldap.system.search({ scope: 'base' }, dn);
 > ```
 >
-> It is the same object, and that is the point: `ldap.system.search(…)` reads
-> as a decision where `ldap.search(…)` reads as a forgotten argument. Some
-> reads are the server's by nature — a uniqueness check has to see a whole
-> branch, and a reference to an entry the caller cannot read is still a valid
-> reference — and those are the ones it names.
+> A lint rule refuses an operation that names neither a request nor
+> `ldap.system`. Hooks run outside the request: what a hook reads or writes
+> to validate, complete or follow an operation is the server's, and a hook
+> acting as the caller passes the request it is handed. Startup and
+> scheduled tasks run outside any request.
+
+> **Read as the server? Judge the caller first.**
+>
+> A read the server makes for a request answers the caller with what it
+> found: a 404 for an entry that is not there, a 400 for a pointer leading
+> nowhere, a 409 for a name taken. Made before the write it prepares is
+> judged, it tells a caller who may not make that write what the directory
+> holds where they cannot read. Have the authorization plugins judge the
+> write first, without making it:
+>
+> ```typescript
+> await this.server.ldap.authorize('ldaprenamerequest', [dn, newDn, req]);
+> // only now: does dn exist, is newDn free, …
+> ```
+>
+> It runs the hooks of the plugins with the `authz` role only, and refuses
+> with their 403 whether the entry is there or not. The write, when made,
+> is judged again with every other hook.
+>
+> A route that finds an entry as the server, across branches, and then
+> answers about it, checks that the caller can read what it found, and
+> answers as for an entry that is not there otherwise:
+>
+> ```typescript
+> if (!(await this.server.ldap.readableBy(dn, req)))
+>   throw new NotFoundError(`User ${id} not found`);
+> ```
 
 #### Search
 
@@ -549,6 +577,24 @@ await this.server.ldap.modify('uid=john,ou=users,dc=example,dc=com', {
 });
 ```
 
+#### Attribute names
+
+An add or a modify names its attributes as the server does before the
+authorization plugins and the hooks see them: `MAIL`, `rfc822Mailbox` or
+the OID of `mail` reach a hook as `mail`, spelled as the configuration or a
+loaded schema spells it. A hook may therefore look an attribute up by that
+name. An option other than `;binary` is refused, as is one attribute named
+twice in one part of a write.
+
+A route that checks a body before handing it to `add` or `modify` names
+its attributes the same way first, and a plugin loading a schema of its
+own says how it spells them:
+
+```typescript
+await this.server.ldap.canonicalChanges(changes); // or canonicalAttributes(entry)
+this.server.ldap.knowAttributeNames(Object.keys(schema.attributes));
+```
+
 #### Delete
 
 ```typescript

package/docs/plugin-development/dependencies.md

@@ -581,7 +581,13 @@ guards.
 
 ## Hook Execution Order
 
-Hooks are executed in the order plugins are loaded. For chained hooks:
+Hooks are executed in the order plugins are loaded, with one exception: the
+request hooks of authorization plugins (`ldapsearchrequest`, `ldapaddrequest`,
+`ldapmodifyrequest`, `ldapdeleterequest`, `ldaprenamerequest`) run before any
+other plugin's, in the order the authorization plugins loaded. The first hook
+to throw answers the request, so a caller who may not make an operation is
+refused before a plugin judges its content, or replaces it.
+`ldapsearchfilter` keeps the load order. For chained hooks:
 
 1. First plugin in chain can modify/validate data
 2. Returns modified data to next plugin
@@ -595,7 +601,7 @@ For non-chained hooks:
 **Example**: `ldapdeleterequest` chain
 
 ```
-Request → trash (moves to trash) → groups (checks members) → organizations (checks empty) → LDAP
+Request → authorization → trash (moves to trash) → groups (checks members) → organizations (checks empty) → LDAP
 ```
 
 ## Creating Plugins with Dependencies

package/docs/plugin-development/hooks.md

@@ -1,14 +1,13 @@
 # Core hooks
 
-Set here the documentation of all hooks.
-
-Typescript definitions into [hooks.ts](./src/hooks.ts)
+The hooks a plugin can register. Their arguments and return values are
+those typed in [hooks.ts](../../src/hooks.ts), which is the reference.
 
 ## Demo hooks
 
-- **hello**: called by [helloworld demo plugin](./src/plugins/helloworld.ts)
+- **hello**: called by [helloworld demo plugin](../../src/plugins/demo/helloworld.ts)
 
-## [LDAP](./src/lib/ldapActions.ts) hooks
+## [LDAP](../../src/lib/ldapActions.ts) hooks
 
 - **ldapopts**: called before any ldapsearch to modify search options
 - **ldapsearchresult**: called after any ldapsearch to modify search result

package/docs/usage/configuration.md

@@ -186,8 +186,10 @@ deployment has run with it on, and a cache that silently serves stale entries
 is not something to switch on for everyone at once.
 
 Writes made through this service (add, modify, rename, move, delete) drop what
-they change, the moved subtree included. Writes made anywhere else do not:
-another replica of this service, an LSC synchronisation, a hand-run
+they change, the moved subtree included, and what the directory's overlays
+change with them: the `memberOf` of the members a group gains or loses, and
+the entries naming an entry renamed or deleted. Writes made anywhere else do
+not: another replica of this service, an LSC synchronisation, a hand-run
 `ldapmodify`. Each process caches on its own, and only its own writes drop what
 it cached. Turn the cache on when this service is the only writer, or when
 serving an entry up to `--ldap-cache-ttl` seconds old is acceptable; leave it
@@ -509,12 +511,13 @@ Formerly `core/twake/calendarResources`, still accepted as a deprecated alias.
 
 #### `core/twake/applicativeAccounts`
 
-| CLI                               | Plural                             | Env                                 | Default       | Description                           |
-| --------------------------------- | ---------------------------------- | ----------------------------------- | ------------- | ------------------------------------- |
-| `--applicative-account-base`      |                                    | `DM_APPLICATIVE_ACCOUNT_BASE`       |               | Applicative accounts base DN          |
-| `--max-app-accounts`              |                                    | `DM_MAX_APP_ACCOUNTS`               | `5`           | Max accounts per user                 |
-| `--applicative-account-attribute` | `--applicative-account-attributes` | `DM_APPLICATIVE_ACCOUNT_ATTRIBUTES` | _(see below)_ | Attributes copied from the user entry |
-| `--ldap-operational-attribute`    | `--ldap-operational-attributes`    | `DM_LDAP_OPERATIONAL_ATTRIBUTES`    | _(see below)_ | Operational attributes to exclude     |
+| CLI                               | Plural                             | Env                                 | Default            | Description                                            |
+| --------------------------------- | ---------------------------------- | ----------------------------------- | ------------------ | ------------------------------------------------------ |
+| `--applicative-account-base`      |                                    | `DM_APPLICATIVE_ACCOUNT_BASE`       |                    | Applicative accounts base DN                           |
+| `--max-app-accounts`              |                                    | `DM_MAX_APP_ACCOUNTS`               | `5`                | Max accounts per user                                  |
+| `--app-accounts-user-attribute`   |                                    | `DM_APP_ACCOUNTS_USER_ATTRIBUTE`    | the mail attribute | Attribute the `:user` of the routes is matched against |
+| `--applicative-account-attribute` | `--applicative-account-attributes` | `DM_APPLICATIVE_ACCOUNT_ATTRIBUTES` | _(see below)_      | Attributes copied from the user entry                  |
+| `--ldap-operational-attribute`    | `--ldap-operational-attributes`    | `DM_LDAP_OPERATIONAL_ATTRIBUTES`    | _(see below)_      | Operational attributes to exclude                      |
 
 Default copied attributes: `objectClass`, `cn`, `sn`, `givenName`, `displayName`, `description` — plus the configured mail attribute, always.
 

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

@@ -61,12 +61,20 @@ Every plugin that judges LDAP operations — `core/auth/authzPerBranch`,
 `core/auth/authzLinid1`, `core/auth/authzDynamic` — registers the same hooks,
 and all of them run: loaded together, they compose as an **AND**, and the
 first refusal wins. The per-caller read filter (`ldapsearchfilter`) is one of
-those hooks: two plugins there compose as an intersection, which is the same
-AND. That is sound when it is meant. When it is not, it is a
+the hooks they register: two plugins there compose as an intersection, which
+is the same AND. That is sound when it is meant. When it is not, it is a
 refusal nobody can explain: `authzPerBranch` beside `authzDynamic` judges a
 machine token by a branch configuration written for administrators, finds
 no entry for the tenant, and refuses a write the token's own ACLs grant.
 
+The authorization plugins' request hooks (`ldapsearchrequest`,
+`ldapaddrequest`, `ldapmodifyrequest`, `ldapdeleterequest`,
+`ldaprenamerequest`) run before any other plugin's, whatever order the
+plugins loaded in: a caller who may not make an operation gets the 403, not
+another plugin's 409, and the operation is not replaced (by
+`core/ldap/trash`, for instance) before it is judged. `ldapsearchfilter`
+keeps the load order.
+
 The AND needs no second plugin to bite. `--authz-per-branch-config` has a
 default — read everywhere, write nowhere — so a lone `authzPerBranch` judges
 **every** authenticated identity, whatever authenticated it: a token that no
@@ -108,6 +116,16 @@ aside — `authzDynamic` letting a request through on
 
 ### What is refused at startup
 
+- An authorization plugin with no authentication plugin is refused: no
+  request carries an identity, so every authorization plugin would step
+  aside and everything would pass while authorization looks on.
+  `authzDynamic`, which authenticates the requests it judges, needs nothing
+  else. With neither kind of plugin, the server serves every request with
+  every right, on purpose (local development, a trusted network); with
+  authentication alone, every authenticated caller has every right (a
+  single administration token, say). The log says which, once. This is
+  checked over the plugins the configuration loads (`--plugin`); a host
+  registering plugins itself answers for what they enforce.
 - Two plugins judging LDAP operations for the same authenticator's requests
   — two branch-level plugins with no `authz_for`, or a branch-level plugin
   judging `authzDynamic`'s tokens — are refused, with both names, unless
@@ -124,7 +142,8 @@ aside — `authzDynamic` letting a request through on
   already.
 
 A host that assembles the server itself — `registerPlugin` after `ready`,
-rather than `--plugin` — gets the same checks, as each plugin arrives: the
+rather than `--plugin` — gets the same checks of the composition, as each
+plugin arrives (not the one asking for an authentication plugin, above): the
 refusal comes out of `registerPlugin`, before any of the plugin's routes or
 hooks exist. An arriving plugin is judged against what is already there, so
 the authentication plugins an `authz_for` or `--authz-scope-source` names

package/docs/usage/plugins/auth/authz-linid1.md

@@ -78,17 +78,26 @@ organization through which entries change hands.
 ```
 
 An entry is **in transit** when it is attached to that organization, or to
-none (with or without the option).
+none (with or without the option). An entry carrying no link is in transit
+on purpose: it is how the entries other tools insert without one are
+caught. Nothing ties such an entry to an organization: any administrator
+may claim it into one they manage, and the first to claim it takes it.
 
-- Every administrator sees the entries in transit.
+- Every administrator sees the entries in transit, but in a global branch
+  (`--authz-global-branch`), which only its holders read.
 - **Claiming** one (`POST /api/v1/ldap/users/:id/move` towards an
-  organization) asks for write on that organization only.
+  organization) asks for write on that organization only. The write
+  claiming it may carry other changes to the entry — its password, say —
+  judged with it: the entry lands in the organization that write is
+  allowed in.
 - **Putting** one in transit asks for write on the organization it leaves,
   and nothing on the transit branch: an administrator only lets go of what
   they manage. Handing an account over to an organization one does not manage
   is two steps: put it in transit, then its new administrator claims it.
-- Any other change to an entry in transit (attributes, password, status,
-  deletion) is judged as before, so the entry is claimed first.
+- Any other change to an entry in transit, not claiming it (attributes,
+  password, status, deletion), is judged as before: on the transit branch
+  for an entry attached to it, on its parent branch for one attached to
+  nothing.
 
 `GET /api/v1/authz/scope` returns the transit branch as `transit` (`null`
 when there is none), so that a client can offer these moves. A group attached

package/docs/usage/plugins/auth/authz-per-branch.md

@@ -106,13 +106,44 @@ Permissions applied to all group members:
 
 ## Permission Resolution
 
-Permissions are resolved in this order:
-
-1. **User-specific permissions** - If user has direct branch permissions, use them
-2. **Group permissions** - Check all groups user belongs to
-3. **Default permissions** - Fall back to defaults if no specific rules match
-
-For each permission type (read/write/delete), the **most permissive** rule wins.
+The rules holding the target, the user's own and those of every group they
+belong to, are combined:
+
+1. **Within one source** (the user's own rules, or one group's), the rule of
+   the **most specific** branch holding the target applies, whatever order
+   the rules are written in, broader rules of that source aside. Branches
+   are compared as DNs, whatever their case and spacing.
+2. **Between sources**, for each permission type (read/write/delete), the
+   **most permissive** wins.
+3. **Default permissions** apply to a permission none of these rules sets. They are a fallback, not a floor: `"default": {"read": true}` does
+   not undo a rule refusing read.
+
+Creating or writing an entry a rule names also asks for that rule's
+permission, and
+moving or deleting one holding such an entry asks for read and write, or
+delete, at every rule below it: a caller granted `ou=organization` cannot
+rename `ou=payroll` from under the rule refusing it, nor change or delete
+the `ou=payroll` entry itself. This holds under
+`--authz-filter-attached-entries` too, where `departmentSync` would relink
+the accounts attached there. A write setting the organization link
+(`--ldap-organization-link-attribute`) is judged on the organizations it
+leaves and joins; anything else it carries still needs write where the
+entry stands: its branch, or, judged by attachment, the organization it
+leaves.
+
+A rule's branch matches a DN however it is spelled, as OpenLDAP reads it:
+case, spaces, escapes (`\2C` and `\,`, `\20` and a space, `\C3\A9` and
+`é`), an attribute type by any of its names or its OID
+(`organizationalUnitName=` and `2.5.4.11=` are `ou=`, learned from the
+directory schema at startup), the spaces its matching rules ignore, and
+the LDAPv2 forms (`;` between RDNs, a value in double quotes). A write is
+judged on the entry as the directory names it, read as the server before
+the write. A caller cannot step around a rule by spelling its branch
+another way.
+
+A move is judged on the mover's own rules. The rules of other users and
+groups name the branch by its DN: once a caller allowed to move it has done
+so, they no longer apply to it, and need rewriting for the new DN.
 
 ## How It Works
 
@@ -212,6 +243,25 @@ With this config, user `manager` can read:
 - `ou=team1,ou=dept1,ou=organization,dc=example,dc=com`
 - ... all descendants
 
+A rule on a sub-branch takes over below it. To keep `manager` out of one
+department:
+
+```json
+{
+  "users": {
+    "manager": {
+      "ou=organization,dc=example,dc=com": { "read": true },
+      "ou=payroll,ou=organization,dc=example,dc=com": { "read": false }
+    }
+  }
+}
+```
+
+A search granted on `ou=organization` then returns nothing from
+`ou=payroll`: each entry it finds is kept only where the caller may read it.
+A group the user belongs to may still grant the department, as the most
+permissive source wins.
+
 ## Examples
 
 ### Example 1: Department-Based Access
@@ -412,8 +462,9 @@ Cache hit/miss logging:
 
 ### Permission Inheritance
 
-- Sub-branch permissions inherit from parent branches
-- Cannot grant more restrictive permissions on sub-branches
+- Sub-branch rules take over from parent branch rules, for what they set
+- A rule may restrict a sub-branch as well as widen it, but another source
+  (a group) granting more still wins
 - Plan branch structure carefully
 
 ### Default Permissions

package/docs/usage/plugins/integrations/app-accounts.md

@@ -100,6 +100,11 @@ DM_MAIL_ATTRIBUTE="mail"
 
 - `--applicative-account-base`: LDAP base DN for applicative accounts (required)
 - `--max-app-accounts`: Maximum number of app accounts per user (default: 5)
+- `--app-accounts-user-attribute`: attribute the `:user` of the routes is
+  matched against (default: the mail attribute, unique directory-wide).
+  `uid` is safe only where a uid is unique across the whole directory: a
+  uid shared by users the caller can read is answered `409`, and one
+  shared with a user it cannot read resolves to the one it can
 - `--mail-attribute`: LDAP attribute for email (default: `mail`)
 - `--api-prefix`: API endpoint prefix (default: `/api`)
 

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

@@ -38,9 +38,42 @@ branch per organization. It serves the groups of an organization under
 ## Routes
 
 Every route answers 404 `ORGANIZATION_NOT_FOUND` when the organization entry
-is missing, and 410 `ORGANIZATION_DELETED` when it is deleted. Errors are
-`{ "error": "...", "code": "..." }`. A request an authorization plugin refuses
-answers 403 `REFUSED`.
+is missing or the caller cannot read it, and 410 `ORGANIZATION_DELETED` when
+it is deleted. Errors are `{ "error": "...", "code": "..." }`. A request an
+authorization plugin refuses answers 403 `REFUSED`.
+
+The routes read as the caller: the authorization plugins decide which groups
+and members it gets. A group it cannot read answers 404, a user it cannot
+read is not found (404 `USER_NOT_FOUND` when adding it), and a member it
+cannot read lists as `{ "uid": "..." }`. A write is judged before anything
+is looked for, so a caller who may not make it gets 403 whether the name is
+taken, the users exist or they are already members.
+
+What the caller may read is the authorization model's to say:
+
+- A model judging by branch (`core/auth/authzPerBranch`) gives an
+  organization's groups and users to the callers granted its branch.
+- A model judging entries by their organization link (`core/auth/authzLinid1`,
+  or `--authz-filter-attached-entries`) gives an entry carrying no link to
+  every administrator. Under such a model only, every group written in an
+  organization's branch — through these routes, SCIM or another plugin — is
+  given the organization link (`--ldap-organization-link-attribute`, with the
+  auxiliary class `twakeGroup` when it holds neither it nor
+  `twakeStaticGroup`), and follows it when moved to another organization; a
+  link naming another organization is refused (400). A group is then judged
+  on its organization: creating or changing one needs write on the
+  organization, not on its group branch only. What stays every
+  administrator's: whether an organization exists or is deleted, its spaces,
+  and users carrying no link, whose link is the provisioning tool's to set.
+  Such users are in transit: any administrator may claim them into an
+  organization they manage, the first to do so taking them — see
+  [transit](../auth/authz-linid1.md#transit-handing-an-entry-over).
+  With `core/ldap/organizations` loaded too, the organizations must lie under
+  `--ldap-top-organization`, where it accepts a link.
+- A plugin judging every read made for the request, as
+  `core/auth/authzDynamic` does, judges the organization check too: an
+  organization its token does not reach answers 404, as one that is not
+  there.
 
 A group reads: