ldap-rest 0.17.1 → 0.19.0

package/docs/client-development/schemas/README.md

@@ -335,18 +335,23 @@ Complete reference for all attribute properties.
 
 ### Attribute Properties Table
 
-| Property   | Type         | Applies To          | Description                                                                      | Example                             |
-| ---------- | ------------ | ------------------- | -------------------------------------------------------------------------------- | ----------------------------------- |
-| `type`     | string       | All                 | Attribute data type: `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"` | `"string"`                          |
-| `required` | boolean      | All                 | Whether the attribute must be present                                            | `true`                              |
-| `fixed`    | boolean      | All                 | Whether the attribute value cannot be changed after creation                     | `true`                              |
-| `role`     | string       | String              | Semantic role for special handling (see [Semantic Roles](#semantic-roles))       | `"identifier"`                      |
-| `test`     | string/regex | String, Array items | Regular expression for validation                                                | `"^[a-zA-Z0-9._-]{1,255}$"`         |
-| `branch`   | string[]     | Pointer             | LDAP branches where referenced entries exist                                     | `["ou=users,dc=example,dc=com"]`    |
-| `ui`       | object       | Pointer             | UI configuration for pointer selection (future feature)                          | `{}`                                |
-| `group`    | string       | All                 | UI grouping for form organization (future feature)                               | `"contact"`                         |
-| `default`  | any          | All                 | Default value for new entries                                                    | `["top", "person"]`                 |
-| `items`    | object       | Array               | Schema for array element validation                                              | `{"type": "string", "test": "..."}` |
+| Property   | Type            | Applies To          | Description                                                                           | Example                             |
+| ---------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
+| `type`     | string          | All                 | Attribute data type: `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`      | `"string"`                          |
+| `required` | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
+| `fixed`    | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
+| `role`     | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
+| `test`     | string/regex    | String, Array items | Regular expression for validation                                                     | `"^[a-zA-Z0-9._-]{1,255}$"`         |
+| `branch`   | string[]        | Pointer             | LDAP branches where referenced entries exist                                          | `["ou=users,dc=example,dc=com"]`    |
+| `ui`       | object          | Pointer             | UI configuration for pointer selection (future feature)                               | `{}`                                |
+| `hint`     | text            | String, Array items | What a valid value looks like, shown under the field and quoted in refusals           | `"Expected pattern 999 9999"`       |
+| `group`    | text            | All                 | Form section the attribute is shown in                                                | `"Mailbox Settings"`                |
+| `default`  | any             | All                 | Default value for new entries                                                         | `["top", "person"]`                 |
+| `items`    | object          | Array               | Schema for array element validation                                                   | `{"type": "string", "test": "..."}` |
+
+A _text_ is a plain string or a map keyed by language tag,
+`{ "en": "Mailbox Settings", "fr": "Paramètres de messagerie" }`, picked as
+[labels are](../../usage/plugins/ldap/flat-generic.md#naming-things-in-the-readers-language).
 
 ### Property Details
 
@@ -394,7 +399,7 @@ Marks the attribute as immutable after creation. Useful for objectClass or ident
 
 #### `role` (Optional)
 
-Assigns semantic meaning to attributes for special handling by the application. See [Semantic Roles](#semantic-roles).
+Assigns semantic meaning to attributes for special handling by the application. See [Semantic Roles](#semantic-roles). An attribute holding several roles lists them: `"role": ["domainName", "displayName"]`.
 
 ```json
 {

package/docs/plugin-development/dependencies.md

@@ -200,9 +200,7 @@ overrides builds a second instance, and it needs a name of its own.
   - `onLdapForwardChange` - Syncs forwarding
   - `onLdapChange` - General LDAP change handling
   - `onLdapDisplayNameChange` - Syncs display name
-  - `ldapgroupadddone` - After group added
-  - `ldapgroupmodifydone` - After group modified
-  - `ldapgroupdeletedone` - After group deleted
+  - `onLdapEntryChange` - Follows team mailboxes
 - **Consumes Hooks**: (Hooks provided by `onLdapChange`)
 - **Notes**: Synchronizes LDAP users/groups with Apache James mail server
 

package/docs/presentations/en.md

@@ -115,7 +115,6 @@ export default class MyPlugin extends DmPlugin {
 - 📧 **Automatic LDAP → James Sync**
 - 🔄 **Mail Address Changes** - Account renaming + data
 - 💾 **Quota Management** - Automatic updates
-- 👥 **Mailing Lists** - LDAP Groups → Address Groups
 - 📨 **Mail Aliases** - mailAlternateAddress → James aliases
 - 🎯 **WebAdmin API** - REST Communication
 
@@ -159,33 +158,6 @@ James WebAdmin: PUT /quota/users/alice@.../size
 
 <!-- end_slide -->
 
-# James Plugin - List Consistency
-
-## LDAP Groups → James Address Groups
-
-```bash
-# Create a group with mail attribute
-POST /api/v1/ldap/groups
-{
-  "cn": "engineering",
-  "mail": "engineering@company.com",
-  "member": ["uid=alice,...", "uid=bob,..."]
-}
-```
-
-### Automatic List Consistency
-
-1. ✅ **Creation** → Group created in James + members added
-2. ✅ **Add Member** → Member added to James list
-3. ✅ **Remove Member** → Member removed from James list
-4. ✅ **Delete Group** → List deleted in James
-
-### Guarantee
-
-**LDAP is the source of truth, James stays synchronized**
-
-<!-- end_slide -->
-
 # LDAP Consistency
 
 ## Automatic Consistency Plugins

package/docs/presentations/fr.md

@@ -115,7 +115,6 @@ export default class MyPlugin extends DmPlugin {
 - 📧 **Synchronisation automatique LDAP → James**
 - 🔄 **Changement d'adresse mail** - Renommage compte + données
 - 💾 **Gestion des quotas** - Mise à jour automatique
-- 👥 **Listes de diffusion** - Groupes LDAP → Address Groups
 - 📨 **Alias mail** - mailAlternateAddress → James aliases
 - 🎯 **WebAdmin API** - Communication via REST
 
@@ -159,33 +158,6 @@ James WebAdmin: PUT /quota/users/alice@.../size
 
 <!-- end_slide -->
 
-# Plugin James - Cohérence des listes
-
-## Groupes LDAP → James Address Groups
-
-```bash
-# Création d'un groupe avec attribut mail
-POST /api/v1/ldap/groups
-{
-  "cn": "engineering",
-  "mail": "engineering@company.com",
-  "member": ["uid=alice,...", "uid=bob,..."]
-}
-```
-
-### Cohérence automatique des listes
-
-1. ✅ **Création** → Groupe créé dans James + membres ajoutés
-2. ✅ **Ajout membre** → Membre ajouté à la liste James
-3. ✅ **Retrait membre** → Membre retiré de la liste James
-4. ✅ **Suppression groupe** → Liste supprimée dans James
-
-### Garantie
-
-**LDAP est la source de vérité, James reste synchronisé**
-
-<!-- end_slide -->
-
 # Cohérence LDAP
 
 ## Plugins de cohérence automatique

package/docs/usage/configuration.md

@@ -452,18 +452,19 @@ whichever of the two names it selects. A value other than `req.user` or
 
 #### `core/twake/james`
 
-| CLI                              | Plural                          | Env                               | Default                 | Description                 |
-| -------------------------------- | ------------------------------- | --------------------------------- | ----------------------- | --------------------------- |
-| `--james-webadmin-url`           |                                 | `DM_JAMES_WEBADMIN_URL`           | `http://localhost:8000` | James WebAdmin API URL      |
-| `--james-webadmin-token`         |                                 | `DM_JAMES_WEBADMIN_TOKEN`         |                         | James authentication token  |
-| `--james-signature-template`     |                                 | `DM_JAMES_SIGNATURE_TEMPLATE`     |                         | Email signature template    |
-| `--james-concurrency`            |                                 | `DM_JAMES_CONCURRENCY`            | `10`                    | James API concurrency       |
-| `--james-init-delay`             |                                 | `DM_JAMES_INIT_DELAY`             | `1000`                  | Init delay (ms)             |
-| `--james-retry-attempts`         |                                 | `DM_JAMES_RETRY_ATTEMPTS`         | `5`                     | Attempts per user call      |
-| `--james-retry-delay`            |                                 | `DM_JAMES_RETRY_DELAY`            | `1000`                  | Base retry delay (ms)       |
-| `--james-mailing-list-branch`    | `--james-mailing-list-branches` | `DM_JAMES_MAILING_LIST_BRANCHES`  | `[]`                    | Mailing list branches       |
-| `--james-mailbox-type-attribute` |                                 | `DM_JAMES_MAILBOX_TYPE_ATTRIBUTE` | `twakeMailboxType`      | Mailbox type attribute      |
-| `--ldap-concurrency`             |                                 | `DM_LDAP_CONCURRENCY`             | `10`                    | LDAP operations concurrency |
+| CLI                              | Plural                          | Env                               | Default                 | Description                                                                               |
+| -------------------------------- | ------------------------------- | --------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
+| `--james-webadmin-url`           |                                 | `DM_JAMES_WEBADMIN_URL`           | `http://localhost:8000` | James WebAdmin API URL                                                                    |
+| `--james-webadmin-token`         |                                 | `DM_JAMES_WEBADMIN_TOKEN`         |                         | James authentication token                                                                |
+| `--james-signature-template`     |                                 | `DM_JAMES_SIGNATURE_TEMPLATE`     |                         | Email signature template                                                                  |
+| `--james-concurrency`            |                                 | `DM_JAMES_CONCURRENCY`            | `10`                    | James API concurrency                                                                     |
+| `--james-init-delay`             |                                 | `DM_JAMES_INIT_DELAY`             | `1000`                  | Init delay (ms)                                                                           |
+| `--james-retry-attempts`         |                                 | `DM_JAMES_RETRY_ATTEMPTS`         | `5`                     | Attempts per user call                                                                    |
+| `--james-retry-delay`            |                                 | `DM_JAMES_RETRY_DELAY`            | `1000`                  | Base retry delay (ms)                                                                     |
+| `--james-mailing-list-branch`    | `--james-mailing-list-branches` | `DM_JAMES_MAILING_LIST_BRANCHES`  | `[]`                    | Branches refused to team mailboxes                                                        |
+| `--james-mailbox-type-attribute` |                                 | `DM_JAMES_MAILBOX_TYPE_ATTRIBUTE` | `twakeMailboxType`      | Mailbox type attribute                                                                    |
+| `--james-sync-forwards`          |                                 | `DM_JAMES_SYNC_FORWARDS`          | `false`                 | Copy LDAP forwards to Twake Mail — [details](plugins/integrations/james-mail.md#forwards) |
+| `--ldap-concurrency`             |                                 | `DM_LDAP_CONCURRENCY`             | `10`                    | LDAP operations concurrency                                                               |
 
 The wait before each retry grows with the attempt, so the total wait is `--james-retry-delay` × n(n−1)/2 for n attempts: 10 s with the defaults, 190 s with 20 attempts.
 

package/docs/usage/plugins/integrations/james-mail.md

@@ -39,6 +39,8 @@ DM_JAMES_WEBADMIN_TOKEN="your-admin-token"
 - `--mail-attribute`: LDAP attribute for email (default: `mail`)
 - `--quota-attribute`: LDAP attribute for quota (default: `mailQuotaSize`)
 - `--alias-attribute`: LDAP attribute for email aliases (default: `mailAlternateAddress`)
+- `--forward-attribute`: LDAP attribute for forwards (default: `mailForwardingAddress`)
+- `--james-sync-forwards`: copy that attribute to Twake Mail's forwards (default: `false`), see [Forwards](#forwards)
 - `--james-mailbox-type-attribute`: LDAP attribute for mailbox type (default: `twakeMailboxType`)
 - `--james-retry-attempts`: attempts in all of a call about a user James may not see yet (default: `5`), see [Replication lag](#replication-lag)
 - `--james-retry-delay`: base delay between those attempts, in ms (default: `1000`); the total wait is delay × n(n−1)/2 for n attempts
@@ -47,55 +49,22 @@ DM_JAMES_WEBADMIN_TOKEN="your-admin-token"
 
 ### Mailing Lists
 
-When a group with a `mail` attribute is created or modified:
+Mailing lists are not synchronized: Twake Mail reads them from LDAP, see
+[Mailing lists](james-mailboxes.md#mailing-lists). Groups whose
+`twakeMailboxType` is `teamMailbox` become James team mailboxes, see
+[James Team Mailboxes](james-mailboxes.md).
 
-1. **Create mailing list**
+### Groups
 
-   ```bash
-   POST /api/v1/ldap/groups
-   {
-     "cn": "engineering",
-     "mail": "engineering@company.com",
-     "member": [
-       "uid=alice,ou=users,dc=example,dc=com",
-       "uid=bob,ou=users,dc=example,dc=com"
-     ]
-   }
-   ```
-
-2. **James plugin** creates address group and adds all members:
-
-   ```http
-   PUT /address/groups/engineering@company.com/alice@company.com
-   PUT /address/groups/engineering@company.com/bob@company.com
-   ```
-
-3. **Add/remove members** - when group members change:
-
-   ```bash
-   POST /api/v1/ldap/groups/engineering/members
-   {"member": "uid=charlie,ou=users,dc=example,dc=com"}
-   ```
-
-   James plugin automatically syncs:
-
-   ```http
-   PUT /address/groups/engineering@company.com/charlie@company.com
-   ```
-
-4. **Delete mailing list** - when group is deleted:
-
-   ```http
-   DELETE /address/groups/engineering@company.com
-   ```
-
-**Notes:**
+James has accounts for users only. An entry whose classes include
+`groupOfNames`, `groupOfUniqueNames` or `groupOfURLs` is a group: the plugin
+creates no identity, quota, alias, forward or delegation for its address, and
+does not rename it in James when its `mail` changes. Its address is a mailing
+list or a team mailbox, as above.
 
-- Only groups with a `mail` attribute are synchronized to James
-- Groups without `mail` are ignored (regular LDAP groups)
-- James Address Groups are simple distribution lists
-- All group members receive emails sent to the group address
-- List type attributes (open/restricted) are stored in LDAP but not enforced by James
+A deployment whose groups (`--group-class`) carry none of these classes has
+its groups handled as users. So is an entry whose classes cannot be read when
+the change is followed.
 
 ### Mail Address Changes
 
@@ -120,7 +89,29 @@ When a user's mail attribute changes:
    POST /users/old@company.com/rename/john.doe@company.com?action=rename
    ```
 
-4. **James** renames the mail account and all associated data
+4. **James** renames the mail account and its mailboxes, and adds a forward
+   from the old address to the new one, so that mail sent to the old address
+   still arrives. It leaves the identities under the old address.
+
+5. **James plugin** moves the aliases (see
+   [Aliases and Mail Changes](#aliases-and-mail-changes)) and gives the new
+   address its [default identity](#display-name-and-identity) back, with the
+   signatures of the old one when `--james-signature-template` is not set.
+
+#### Forwards Left on an Address
+
+The forward a rename leaves outlives the account. When an address becomes the
+`mail` or an alias of an account, at its creation, a rename, a mail added to
+an existing entry or an alias add, the plugin removes the forwards James holds
+from it, except the entry's own when the directory owns forwards
+(`--forward-attribute`, with `--james-sync-forwards`):
+
+```http
+GET /address/forwards/old@company.com
+DELETE /address/forwards/old@company.com/targets/john.doe@company.com
+```
+
+Otherwise the new owner of the address would not get its mail.
 
 ### Quota Changes
 
@@ -148,11 +139,33 @@ When a user's quota changes:
    5000000000
    ```
 
+### Forwards
+
+Forwards are a setting of the user in Twake Mail, beside "keep a copy in my
+mailbox", and Twake Mail Admin can change them too. By default the plugin
+does not copy `--forward-attribute` to them. It still removes the
+[forwards left](#forwards-left-on-an-address) on an address an account takes:
+Twake Mail keeps a user's forwards under their own address, and none can have
+been set on an address the account is only now taking.
+
+With `--james-sync-forwards`, the directory owns them: each change of
+`--forward-attribute` is applied to Twake Mail, and overwrites what the user
+set there.
+
+```http
+PUT /address/forwards/jdoe@company.com/targets/john@partner.com
+DELETE /address/forwards/jdoe@company.com/targets/old@partner.com
+```
+
+Only the change is applied: a forward the user added in Twake Mail stays
+until the directory names it and removes it, and the directory is never told
+about the forwards set in Twake Mail.
+
 ### Display Name and Identity
 
-When a user is added, or their display name changes, the plugin names their
-default identity in Twake Mail after the directory. The name is the first one
-found in `--display-name-attribute` (`displayName` by default), `cn`, then
+When a user is added, renamed, or their display name changes, the plugin names
+their default identity in Twake Mail after the directory. The name is the first
+one found in `--display-name-attribute` (`displayName` by default), `cn`, then
 `givenName` and `sn`. The optional signature is `--james-signature-template`.
 
 1. **James plugin** reads the default identity, the deletable one with the
@@ -259,7 +272,8 @@ When the primary email address changes, all aliases are automatically updated:
    PUT /address/aliases/john.smith@company.com/sources/jdoe@company.com
    ```
 
-   **Note:** James automatically creates an alias from the old address when renaming a user. The plugin attempts to create this alias explicitly, but handles the 409 Conflict response gracefully if it already exists.
+   James forwards the old address to the new one, see
+   [Forwards Left on an Address](#forwards-left-on-an-address).
 
 #### Active Directory Format Support
 
@@ -463,14 +477,19 @@ const signature = await james.generateSignature(
 
 ---
 
-### updateJamesIdentity(dn, mail, displayName)
+### updateJamesIdentity(dn, mail, displayName, signatures?)
 
 Update a user's JMAP identity in James (name and optional signature).
 
 **Signature:**
 
 ```typescript
-async updateJamesIdentity(dn: string, mail: string, displayName: string): Promise<void>
+async updateJamesIdentity(
+  dn: string,
+  mail: string,
+  displayName: string,
+  signatures?: { htmlSignature?: string; textSignature?: string }
+): Promise<void>
 ```
 
 **Parameters:**
@@ -478,6 +497,8 @@ async updateJamesIdentity(dn: string, mail: string, displayName: string): Promis
 - `dn` (string): LDAP Distinguished Name (used for signature generation)
 - `mail` (string): User's email address
 - `displayName` (string): New display name for the identity
+- `signatures` (object, optional): written when `--james-signature-template`
+  is not set
 
 **Example:**
 
@@ -575,18 +596,17 @@ const type = await james.getGroupMailboxType(
 
 ### Endpoints Used
 
-| Operation           | Endpoint                                   | Method |
-| ------------------- | ------------------------------------------ | ------ |
-| Rename account      | `/users/{old}/rename/{new}?action=rename`  | POST   |
-| Update quota        | `/quota/users/{mail}/size`                 | PUT    |
-| Get quota           | `/quota/users/{mail}`                      | GET    |
-| Add delegation      | `/users/{mail}/authorizedUsers/{delegate}` | PUT    |
-| Remove delegation   | `/users/{mail}/authorizedUsers/{delegate}` | DELETE |
-| Add alias           | `/address/aliases/{mail}/sources/{alias}`  | PUT    |
-| Remove alias        | `/address/aliases/{mail}/sources/{alias}`  | DELETE |
-| Add group member    | `/address/groups/{group}/{member}`         | PUT    |
-| Remove group member | `/address/groups/{group}/{member}`         | DELETE |
-| Delete group        | `/address/groups/{group}`                  | DELETE |
+| Operation         | Endpoint                                   | Method |
+| ----------------- | ------------------------------------------ | ------ |
+| Rename account    | `/users/{old}/rename/{new}?action=rename`  | POST   |
+| Update quota      | `/quota/users/{mail}/size`                 | PUT    |
+| Get quota         | `/quota/users/{mail}`                      | GET    |
+| Add delegation    | `/users/{mail}/authorizedUsers/{delegate}` | PUT    |
+| Remove delegation | `/users/{mail}/authorizedUsers/{delegate}` | DELETE |
+| Add alias         | `/address/aliases/{mail}/sources/{alias}`  | PUT    |
+| Remove alias      | `/address/aliases/{mail}/sources/{alias}`  | DELETE |
+| List forwards     | `/address/forwards/{mail}`                 | GET    |
+| Remove forward    | `/address/forwards/{mail}/targets/{to}`    | DELETE |
 
 ### Authentication
 
@@ -727,11 +747,9 @@ defaults, 190 seconds with 20 attempts. `--james-retry-attempts 1` disables
 the retries. Other
 failures, such as 401 or 500, are not retried, nor are deletions.
 
-The group calls are not retried: James does not look the members up in its
-users repository there. Address groups (`/address/groups`) accept any valid
-address, and the member routes of a TMail team mailbox do not check the user;
-their only 404 is a missing team mailbox, which is avoided by creating it
-before adding the members.
+The team mailbox calls are not retried: their member routes do not check
+the user in James's users repository; their only 404 is a missing team
+mailbox, which is avoided by creating it before adding the members.
 
 The retries run in the background, after the LDAP write has answered; a
 call waiting for its next attempt does not take a slot of
@@ -821,9 +839,10 @@ Quota values are in **bytes**:
 
 ### Scenario 1: User Creation
 
-1. Create user in LDAP with mail attribute
-2. James plugin does nothing (user doesn't exist in James yet)
-3. Create mail account in James manually or via provisioning script
+1. Create user in LDAP with mail attribute: James reads its users from LDAP
+2. James plugin sets the quota, the aliases and the default identity, after
+   dropping the [forwards left](#forwards-left-on-an-address) on its addresses
+3. A mail added later to an existing entry is handled the same way
 4. Future mail/quota changes are synced automatically
 
 ### Scenario 2: Mail Address Change
@@ -846,68 +865,12 @@ Quota values are in **bytes**:
 3. If user is over new quota, James may block incoming mail
 4. User must delete mail to get under quota
 
-## Mailing List Examples
-
-### Creating a Mailing List
-
-```bash
-# Create a group with mail attribute
-curl -X POST http://localhost:8081/api/v1/ldap/groups \
-  -H "Authorization: Bearer admin-token" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "cn": "engineering",
-    "mail": "engineering@company.com",
-    "member": [
-      "uid=alice,ou=users,dc=example,dc=com",
-      "uid=bob,ou=users,dc=example,dc=com"
-    ],
-    "twakeDepartmentLink": "ou=organization,dc=example,dc=com",
-    "twakeDepartmentPath": "Engineering"
-  }'
-```
-
-The James plugin automatically creates the mailing list and adds all members.
-
-### Adding a Member
-
-```bash
-# Add member to existing group
-curl -X POST http://localhost:8081/api/v1/ldap/groups/engineering/members \
-  -H "Authorization: Bearer admin-token" \
-  -H "Content-Type: application/json" \
-  -d '{"member": "uid=charlie,ou=users,dc=example,dc=com"}'
-```
-
-James is automatically updated to include charlie@company.com in the distribution list.
-
-### Removing a Member
-
-```bash
-# Remove member from group
-curl -X DELETE http://localhost:8081/api/v1/ldap/groups/engineering/members/uid=alice,ou=users,dc=example,dc=com \
-  -H "Authorization: Bearer admin-token"
-```
-
-James removes alice@company.com from the mailing list.
-
-### Deleting a Mailing List
-
-```bash
-# Delete the entire group
-curl -X DELETE http://localhost:8081/api/v1/ldap/groups/engineering \
-  -H "Authorization: Bearer admin-token"
-```
-
-James deletes the entire address group.
-
 ## Limitations
 
 1. **One-way sync**: LDAP → James only. James changes don't sync back to LDAP.
 2. **No account creation**: Plugin doesn't create James accounts, only updates existing ones.
 3. **No user deletion**: deleting an LDAP user leaves its James data (mailboxes, quota, aliases) as it is; purging it is left to James.
 4. **Synchronous**: James API calls block LDAP response. Slow James = slow LDAP.
-5. **No send restrictions**: James doesn't enforce list type restrictions (open/member/owner-only). These are metadata in LDAP only.
 
 ## Advanced Configuration