ldap-rest 0.6.2 → 0.8.0

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

@@ -139,6 +139,178 @@ Fixed attributes:
 - Cannot be modified after creation
 - Cannot be deleted
 
+### Naming things, in the reader's language
+
+`label` is what a client shows instead of the attribute name, and `entity.label`
+/ `entity.singularLabel` are what it calls the collection and one of its
+entries. Each may be a plain string, or a map keyed by language tag:
+
+```json
+{
+  "entity": {
+    "name": "twakeUser",
+    "singularName": "user",
+    "pluralName": "users",
+    "label": { "en": "Users", "fr": "Utilisateurs" },
+    "singularLabel": { "en": "user", "fr": "utilisateur" }
+  },
+  "attributes": {
+    "twakeDepartmentLink": {
+      "type": "pointer",
+      "role": "organizationLink",
+      "label": { "en": "Department", "fr": "Organisation" }
+    }
+  }
+}
+```
+
+These words name _your_ entities and attributes, so their translations belong
+in your schemas rather than in a catalogue shipped with the product — which is
+also why an interface can be fully translated without the product learning what
+you call a department. A client picks the exact tag, then its language, then
+English, then whatever the map does hold; with no label at all it falls back to
+the attribute name made readable.
+
+A nomenclature names its values too. `entity.valueLabels` maps the main
+attribute value of an entry to what a client shows for it, so a group whose
+type is `cn=teamMailbox,…` reads _Shared mailbox_ — or _Boîte partagée_ —
+wherever a pointer lands on it:
+
+```json
+{
+  "entity": {
+    "name": "twakeMailboxType",
+    "mainAttribute": "cn",
+    "valueLabels": {
+      "group": { "en": "Group", "fr": "Groupe" },
+      "teamMailbox": { "en": "Shared mailbox", "fr": "Boîte partagée" }
+    }
+  }
+}
+```
+
+A value the map does not hold is shown as it is stored: a directory with a
+value of its own keeps working, and names it by adding it to its schema.
+
+### Explaining a pattern: `hint`
+
+A `test` tells the server what to refuse. A `hint` tells the person what to
+type, before they get it wrong:
+
+```json
+{
+  "telephoneNumber": {
+    "type": "string",
+    "test": "^\\(\\+99\\)\\s\\d{3}\\s\\d{4}$",
+    "hint": "Expected pattern (+99) 999 9999"
+  }
+}
+```
+
+The hint travels with the schema, so a client shows it under the field and the
+server repeats it when it rejects a value — the pattern and its explanation
+cannot drift apart, and neither is hardcoded in the interface.
+
+### Attributes a client may not send
+
+| Marker      | Meaning                                                                         |
+| ----------- | ------------------------------------------------------------------------------- |
+| `generated` | The server computes the value. A request that carries it is refused with a 400. |
+| `readOnly`  | The value is derived elsewhere — `memberOf` is driven from the group side.      |
+
+Both restrict the **request body** only: the core and its plugins still write
+these attributes.
+
+### Attributes a client never receives
+
+`neverReturn` strips an attribute from every API answer while leaving it
+writable. It is what makes "a manager may reset a password without being able
+to read it" a projection rather than an authorization engine:
+
+```json
+{
+  "userPassword": { "type": "string", "role": "password", "neverReturn": true },
+  "pwdReset": {
+    "type": "boolean",
+    "role": "passwordReset",
+    "neverReturn": true
+  }
+}
+```
+
+### Deriving the identifier
+
+When the RDN is not something a person chooses, `generatedFrom` says where it
+comes from. The client then posts without it:
+
+```json
+{
+  "uid": {
+    "type": "string",
+    "role": "identifier",
+    "generated": true,
+    "generatedFrom": {
+      "attribute": "mail",
+      "extract": "^([^@]+)@",
+      "lowercase": true,
+      "onCollision": "suffix"
+    }
+  }
+}
+```
+
+`onCollision` decides what happens when the value is taken — two directories'
+worth of `jean.dupont@a.example` and `jean.dupont@b.example` map to the same
+local part. `suffix` appends `-2`, `-3`, …; `error` (the default) refuses the
+creation with a 409.
+
+### Semantic roles
+
+`role` says what an attribute _means_, so core code and plugins can find it
+without knowing its name. `roleAttribute(schema, 'accountStatus')` returns
+`twakeAccountStatus` in a Twake directory and whatever another deployment
+chose in its own. The roles the core looks for:
+
+| Role                                   | Meaning                                       |
+| -------------------------------------- | --------------------------------------------- |
+| `identifier`, `displayName`            | RDN value, human-readable name                |
+| `primaryEmail`, `emailAliases`         | Mail addresses of the entry                   |
+| `emailQuota`                           | Mailbox size limit, in bytes                  |
+| `organizationLink`, `organizationPath` | Organization the entry belongs to             |
+| `members`, `owners`                    | Members of a group, and who may write to it   |
+| `accountStatus`, `accountExpiry`       | Lifecycle state and scheduled removal         |
+| `password`, `passwordReset`            | Credential and "change it at next login" flag |
+| `domainLink`, `domainName`             | Mail domains an organization may use          |
+
+An attribute may carry several roles (`"role": ["identifier", "displayName"]`),
+and a deployment is free to add its own for its plugins.
+
+### Which attributes a search covers: `searchable`
+
+`GET /{pluralName}?match=…&attribute=…` takes one attribute name or several
+separated by commas, and an entry matching any of them is returned. Which ones
+a client should offer is a property of the deployment rather than of the code:
+a substring filter on an attribute the directory has not indexed scans the
+branch.
+
+`"searchable": true` says so. A schema that marks even one attribute has
+declared its list, and that list is what a client searches; a schema that
+marks none leaves the client to guess — everything returnable, single-valued
+and not a DN, which suits a small branch and scans a large one. The shipped
+schemas mark the attributes an operator looks people up by:
+
+```json
+"sn": { "type": "string", "searchable": true, "label": { … } }
+```
+
+Align it with your indexes. In OpenLDAP that means `index sn,cn,mail sub` for
+the attributes you mark.
+
+The remaining markers — `unique`, `normalize`, `states`,
+`referentialIntegrity`, `deleteGuard`, `mailDomainScope` — are read by
+[enterprise-rules](enterprise-rules.md) and
+[account-lifecycle](account-lifecycle.md).
+
 ## Generated APIs
 
 For each schema, the plugin generates REST API endpoints:

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

@@ -41,7 +41,7 @@ This plugin manages groups stored as `groupOfNames` or similar object classes in
 
 ### Important Notes
 
-- **Empty Groups**: `groupOfNames` requires at least one member. The plugin uses a dummy member (configurable via `--group-dummy-user`) for empty groups.
+- **Empty Groups**: `groupOfNames` requires at least one member. The plugin uses a dummy member (configurable via `--group-dummy-user`) for empty groups. That dummy member is hidden from `member` on both `GET /ldap/groups` and `GET /ldap/groups/{cn}`, so a client never sees it as a real one.
 - **Member Validation**: By default, the plugin validates that all members exist in LDAP before adding them. Set `--groups-allow-unexistent-members true` to disable validation.
 - **Automatic Cleanup**: When a user is deleted, the plugin automatically removes them from all groups via the `ldapdeleterequest` hook.
 
@@ -55,13 +55,17 @@ GET /api/v1/ldap/groups
 
 **Query Parameters:**
 
-- `match` (optional): Filter by group name (supports wildcards and LDAP filters)
+- `match` (optional): Value to look for
+- `attribute` (optional): Attribute(s) `match` is looked for in, as a
+  substring, several separated by commas — the same semantics as the flat
+  entity lists. Without it, `match` is either a raw LDAP filter (when it
+  contains `=`) or an exact group name.
 - `attributes` (optional): Comma-separated list of attributes to return
 
 **Example:**
 
 ```bash
-curl "http://localhost:8081/api/v1/ldap/groups?match=admin*&attributes=cn,member,description"
+curl "http://localhost:8081/api/v1/ldap/groups?match=admin&attribute=cn,mail&attributes=cn,member,description"
 ```
 
 **Response (200):**
@@ -150,7 +154,9 @@ POST /api/v1/ldap/groups
 
 - `cn` is required
 - `member` can be a string (single member) or array (multiple members)
-- If no members provided, a dummy member is automatically added
+- 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
+  single-group endpoint
 - Additional attributes can be included based on schema
 
 **Response (200):**

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

@@ -51,8 +51,10 @@ Organizations are hierarchical LDAP entries:
 
 - Use LDAP DN structure for hierarchy
 - Have a `twakeDepartmentPath` attribute showing their position in the tree
-- Example: `ou=IT,ou=Departments,dc=example,dc=com`
-  - Path: `IT / Departments / Top Organization`
+- The path reads from the root down, the entry's own name last, and stops
+  below the top organization: a top-level organization's path is its own name
+- Example: `ou=IT,ou=Departments,ou=organization,dc=example,dc=com`
+  - Path: `Departments / IT`
 
 ### Users and Groups
 
@@ -64,8 +66,8 @@ Users and groups reference organizations via:
   ```json
   {
     "uid": "john.doe",
-    "twakeDepartmentLink": "ou=IT,ou=Departments,dc=example,dc=com",
-    "twakeDepartmentPath": "IT / Departments / Top Organization"
+    "twakeDepartmentLink": "ou=IT,ou=Departments,ou=organization,dc=example,dc=com",
+    "twakeDepartmentPath": "Departments / IT"
   }
   ```
 
@@ -118,7 +120,7 @@ curl "http://localhost:8081/api/v1/ldap/organizations/ou%3DIT%2Co%3Dgov%2Cc%3Dmu
   "dn": "ou=IT,dc=example,dc=com",
   "ou": "IT",
   "description": "Information Technology Department",
-  "twakeDepartmentPath": "IT / Government"
+  "twakeDepartmentPath": "Government / IT"
 }
 ```
 
@@ -185,7 +187,7 @@ POST /api/v1/ldap/organizations
   "ou": "IT",
   "parentDn": "dc=example,dc=com",
   "description": "Information Technology Department",
-  "twakeDepartmentPath": "IT / Government"
+  "twakeDepartmentPath": "Government / IT"
 }
 ```
 
@@ -264,7 +266,10 @@ POST /api/v1/ldap/organizations/:dn/move
 
 - Moves an organization to a different parent organization
 - The organization will become a child of the target organization
-- All sub-organizations and linked entities (users/groups) move with it
+- All sub-organizations and linked entities (users/groups) move with it. With
+  `core/ldap/departmentSync` loaded, the path of the organization and of every
+  sub-organization is recomputed, then the linked entities take the new link
+  and path; without it, those paths keep naming the former parent
 - Cannot move an organization into itself or its own descendants (circular reference prevention)
 - Cannot move to the same parent (no-op)
 - Target must be a valid organizational unit
@@ -340,10 +345,14 @@ The plugin enforces several validation rules through hooks:
 ### For Organizations
 
 1. **Path Validation**: The `twakeDepartmentPath` must:
-   - Start with the organization's own `ou` name
-   - Be followed by the path separator
-   - Reference an existing parent organization in the hierarchy
-   - Match the actual LDAP DN structure
+   - End with the organization's own `ou` name, preceded by the path separator
+   - Be preceded by the stored path of an existing organization
+   - Be its own name alone only when the entry hangs directly from the top
+     organization, which its DN has to say
+   - A path written the other way round, the entry's own name first and the
+     top organization's name last, is accepted as it stands: it is what
+     directories written before this convention hold. The server never
+     computes one.
 
 2. **Deletion Protection**: Organizations can only be deleted if:
    - No users have `twakeDepartmentLink` pointing to it
@@ -385,9 +394,10 @@ hooks: {
     if (!isOrganization(entry)) {
       await checkDeptLink(entry); // Validates link exists
     }
-    // If entry is an organization, validate path
+    // If entry is an organization, validate path against the DN it is
+    // written at: that is what says where the entry hangs from
     if (isOrganization(entry)) {
-      await checkDeptPath(entry); // Validates path matches hierarchy
+      await checkDeptPath(entry, dn); // Validates path matches hierarchy
     }
     return [dn, entry];
   };
@@ -417,13 +427,13 @@ curl -X POST http://localhost:8081/api/v1/ldap/organizations \
   -H "Content-Type: application/json" \
   -d '{
     "ou": "Recruitment",
-    "parentDn": "ou=HR,dc=example,dc=com",
-    "description": "Recruitment Team",
-    "twakeDepartmentPath": "Recruitment / HR / Government"
+    "parentDn": "ou=HR,ou=organization,dc=example,dc=com",
+    "description": "Recruitment Team"
   }'
+# `twakeDepartmentPath` is computed by the server: `HR / Recruitment`
 ```
 
-This creates: `ou=Recruitment,ou=HR,dc=example,dc=com`
+This creates: `ou=Recruitment,ou=HR,ou=organization,dc=example,dc=com`
 
 ### Example 3: Get Organization Hierarchy
 
@@ -493,7 +503,7 @@ curl -X POST http://localhost:8081/api/v1/ldap/users \
     "sn": "Doe",
     "mail": "john.doe@example.com",
     "twakeDepartmentLink": "ou=IT,dc=example,dc=com",
-    "twakeDepartmentPath": "IT / Government"
+    "twakeDepartmentPath": "Government / IT"
   }'
 ```
 
@@ -513,7 +523,7 @@ curl -X POST http://localhost:8081/api/v1/ldap/groups \
     "cn": "it-admins",
     "description": "IT Administrators",
     "twakeDepartmentLink": "ou=IT,dc=example,dc=com",
-    "twakeDepartmentPath": "IT / Government",
+    "twakeDepartmentPath": "Government / IT",
     "member": ["uid=john.doe,ou=users,dc=example,dc=com"]
   }'
 ```
@@ -538,31 +548,47 @@ You must first:
 
 ### Path Format
 
-The path attribute follows this pattern:
+The path attribute follows this pattern, the top organization excluded:
 
 ```
-{current_ou} / {parent_ou} / {grandparent_ou} / ... / {top_org}
+{parent_of_parent_ou} / {parent_ou} / {current_ou}
 ```
 
 ### Validation Process
 
-1. **Extract Components**: Split path by separator
-2. **Verify First Component**: Must match organization's own `ou`
-3. **Validate Parent Path**: Search for parent organization with matching path
-4. **Verify Hierarchy**: Ensure path matches actual LDAP DN structure
+1. **Verify Last Component**: Must match the organization's own `ou`
+2. **Validate Parent Path**: What precedes it must be the stored path of an
+   existing organization
+3. **Verify Hierarchy**: An organization whose path is its own name alone must
+   hang directly from the top organization
+4. **Accept The Old Form**: A path reading the other way round, ending in the
+   top organization's own name, is left alone — the directories that hold
+   them predate this convention and their entries have to stay writable
 
 ### Example Path Validation
 
-For organization: `ou=Recruitment,ou=HR,dc=example,dc=com`
+For organization: `ou=Recruitment,ou=HR,ou=organization,dc=example,dc=com`
 
-Valid path: `Recruitment / HR / Government`
+Valid path: `HR / Recruitment`
 
-- `Recruitment` matches current ou
-- `HR / Government` must exist as path of `ou=HR,dc=example,dc=com`
+- it ends with `Recruitment`, the entry's own `ou`
+- what precedes it, `HR`, must be the stored path of an existing organization
 
-Invalid path: `Recruitment / IT / Government`
+Invalid path: `IT / Recruitment`
 
-- `IT / Government` doesn't match parent's actual path
+- no organization holds the path `IT`
+
+Invalid path: `Recruitment / HR`
+
+- it ends with `HR`, not with the entry's own name
+
+Invalid path: `Recruitment`
+
+- it names no parent, and the entry does not hang from the top organization
+
+Accepted path: `Recruitment / HR / organization`
+
+- the old form, the top organization last: read, not written
 
 ## Troubleshooting
 
@@ -576,7 +602,7 @@ Invalid path: `Recruitment / IT / Government`
 # Create organization first
 curl -X POST http://localhost:8081/api/v1/ldap/organizations \
   -H "Content-Type: application/json" \
-  -d '{"ou": "IT", "twakeDepartmentPath": "IT / Government"}'
+  -d '{"ou": "IT"}'  # the path is computed by the server
 
 # Then create user with link
 curl -X POST http://localhost:8081/api/v1/ldap/users \
@@ -591,7 +617,7 @@ curl -X POST http://localhost:8081/api/v1/ldap/users \
 
 1. Ensure parent path exists and matches LDAP hierarchy
 2. Verify separator matches configured separator (default: `" / "`)
-3. Check that path starts with organization's own `ou` name
+3. Check that the path ends with the organization's own `ou` name
 
 ### Cannot Delete Organization