ldap-rest 0.0.1

package/docs/ldapTrash.md

@@ -0,0 +1,260 @@
+# LDAP Trash Plugin
+
+Plugin to intercept LDAP delete operations and move entries to a trash branch instead of permanently deleting them.
+
+## Features
+
+- **Soft Delete**: Moves entries to trash instead of permanent deletion
+- **Configurable Branches**: Watch specific LDAP branches or all branches
+- **Metadata Tracking**: Automatically adds deletion timestamp and original DN
+- **Auto-create Trash**: Creates trash branch automatically if it doesn't exist
+- **Atomic Move**: Uses LDAP modifyDN for safe, atomic operations
+- **Overwrite Protection**: Automatically removes old trash entries when moving new ones
+
+## Configuration
+
+### Environment Variables
+
+- `DM_TRASH_BASE`: LDAP base DN for trash (default: `ou=trash,dc=example,dc=com`)
+- `DM_TRASH_WATCHED_BASES`: Comma-separated list of branches to watch (default: all branches except trash)
+- `DM_TRASH_ADD_METADATA`: Add metadata to trashed entries (default: `true`)
+- `DM_TRASH_AUTO_CREATE`: Auto-create trash branch if missing (default: `true`)
+
+### Command Line
+
+```bash
+--plugin core/ldap/trash \
+--trash-base "ou=trash,dc=example,dc=com" \
+--trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com" \
+--trash-add-metadata true \
+--trash-auto-create true
+```
+
+## How It Works
+
+When a delete operation occurs:
+
+1. **Check if DN is watched**: Plugin checks if the DN is in a configured watched branch
+2. **Ensure trash exists**: Creates trash branch if needed (when `auto-create` is enabled)
+3. **Remove old trash entry**: If an entry with the same RDN exists in trash, it's deleted first
+4. **Atomic move**: Uses LDAP `modifyDN` to move the entry to trash
+5. **Add metadata**: Adds deletion timestamp and original DN as `description` attribute
+6. **Cancel native delete**: The original delete operation is cancelled
+
+### DN Transformation
+
+Original DN is transformed to trash DN by replacing the parent branch:
+
+```
+Before: uid=john,ou=users,dc=example,dc=com
+After:  uid=john,ou=trash,dc=example,dc=com
+```
+
+## Usage Examples
+
+### Watch All Branches (Default)
+
+```bash
+ldap-rest \
+  --plugin core/ldap/trash \
+  --trash-base "ou=trash,dc=example,dc=com"
+```
+
+This watches all LDAP branches except the trash branch itself.
+
+### Watch Specific Branches Only
+
+```bash
+ldap-rest \
+  --plugin core/ldap/trash \
+  --trash-base "ou=trash,dc=example,dc=com" \
+  --trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com"
+```
+
+This only intercepts deletes from `ou=users` and `ou=groups`. Deletes from other branches proceed normally.
+
+### Disable Metadata
+
+```bash
+ldap-rest \
+  --plugin core/ldap/trash \
+  --trash-base "ou=trash,dc=example,dc=com" \
+  --trash-add-metadata false
+```
+
+Entries are moved to trash without adding deletion metadata.
+
+### Manual Trash Branch
+
+If you want to create the trash branch manually:
+
+```bash
+# Create trash branch manually
+ldapadd -x -D "cn=admin,dc=example,dc=com" -W <<EOF
+dn: ou=trash,dc=example,dc=com
+objectClass: top
+objectClass: organizationalUnit
+ou: trash
+description: LDAP Trash - Deleted entries are moved here
+EOF
+
+# Configure plugin to not auto-create
+ldap-rest \
+  --plugin core/ldap/trash \
+  --trash-base "ou=trash,dc=example,dc=com" \
+  --trash-auto-create false
+```
+
+## Metadata Format
+
+When `trash-add-metadata` is enabled, the plugin adds a `description` attribute to trashed entries:
+
+```
+description: Deleted on 2025-10-15T10:30:45.123Z from uid=john,ou=users,dc=example,dc=com
+```
+
+This helps track:
+
+- When the entry was deleted
+- Where it originally existed
+
+## Recovering from Trash
+
+To restore an entry from trash, manually move it back using LDAP tools:
+
+```bash
+# List entries in trash
+ldapsearch -x -b "ou=trash,dc=example,dc=com" "(objectClass=*)"
+
+# Restore user (move back)
+ldapmodrdn -x -D "cn=admin,dc=example,dc=com" -W \
+  "uid=john,ou=trash,dc=example,dc=com" \
+  "uid=john" \
+  -s "ou=users,dc=example,dc=com"
+```
+
+Or use a script:
+
+```javascript
+// Restore from trash
+await dm.ldap.move(
+  'uid=john,ou=trash,dc=example,dc=com',
+  'uid=john,ou=users,dc=example,dc=com'
+);
+
+// Clean up metadata (optional)
+await dm.ldap.modify('uid=john,ou=users,dc=example,dc=com', {
+  delete: { description: [] },
+});
+```
+
+## Emptying Trash
+
+To permanently delete entries from trash:
+
+```bash
+# Delete specific entry from trash
+ldapdelete -x -D "cn=admin,dc=example,dc=com" -W \
+  "uid=john,ou=trash,dc=example,dc=com"
+
+# Empty entire trash (careful!)
+ldapsearch -x -b "ou=trash,dc=example,dc=com" -LLL dn | \
+  grep '^dn:' | cut -d' ' -f2 | \
+  while read dn; do
+    if [ "$dn" != "ou=trash,dc=example,dc=com" ]; then
+      ldapdelete -x -D "cn=admin,dc=example,dc=com" -W "$dn"
+    fi
+  done
+```
+
+Note: Deleting from trash itself is NOT intercepted by the plugin (prevents infinite loops).
+
+## LDAP Permissions
+
+The plugin requires `modifyDN` permission to move entries. Ensure your LDAP bind DN has sufficient permissions:
+
+```ldif
+# Example ACL for OpenLDAP
+olcAccess: to dn.subtree="dc=example,dc=com"
+  by dn="cn=admin,dc=example,dc=com" write
+  by * read
+```
+
+If you get permission errors, check your LDAP ACLs and ensure the bind DN can:
+
+- Read entries from watched branches
+- Move entries to trash branch (modifyDN)
+- Modify entries in trash (to add metadata)
+
+## Hooks
+
+This plugin uses the `ldapdeleterequest` hook to intercept delete operations before they occur.
+
+## Limitations
+
+- Only works with flat entries (RDN is preserved, parent DN is changed)
+- Entries with the same RDN will overwrite previous trash entries
+- Tree structures (entries with children) must be deleted leaf-first
+- Does not track history (only keeps the latest deleted version)
+
+## Troubleshooting
+
+### Trash not being created
+
+1. Check `auto-create` is enabled (default)
+2. Verify bind DN has permission to create `ou=trash`
+3. Check logs for error messages
+
+### Entries not moving to trash
+
+1. Check if DN matches `watched-bases` configuration
+2. Verify bind DN has `modifyDN` permission
+3. Check that trash branch exists
+4. Review logs for specific error messages
+
+### Permission errors
+
+```
+Error: Trash plugin: Insufficient LDAP permissions to move uid=john,ou=users,dc=example,dc=com to trash
+```
+
+Solution: Grant `modifyDN` permission to the bind DN in LDAP ACLs.
+
+### Overwrite warnings
+
+If you see messages about removing old trash entries, this is normal behavior. The plugin ensures only one version of each entry exists in trash.
+
+## Best Practices
+
+1. **Regular cleanup**: Schedule periodic trash cleanup to prevent unlimited growth
+2. **Backup first**: Always backup LDAP before emptying trash
+3. **Monitor trash size**: Track the number of entries in trash
+4. **Document recovery**: Document the recovery process for your team
+5. **Test permissions**: Verify LDAP permissions before deploying to production
+6. **Watch selectively**: Only watch branches that need trash protection
+
+## Example Configuration
+
+Full production setup:
+
+```bash
+ldap-rest \
+  --plugin core/auth/token \
+  --plugin core/ldap/trash \
+  --plugin core/ldap/flatGeneric \
+  --plugin core/ldap/groups \
+  --ldap-url "ldap://localhost:389" \
+  --ldap-dn "cn=admin,dc=example,dc=com" \
+  --ldap-pwd "admin" \
+  --ldap-base "dc=example,dc=com" \
+  --trash-base "ou=trash,dc=example,dc=com" \
+  --trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com" \
+  --trash-add-metadata true \
+  --auth-token "secret-token"
+```
+
+## License
+
+[![Powered by LINAGORA](./linagora.png)](https://linagora.com)
+
+License: [AGPL-3.0](../LICENSE), copyright 2025-present LINAGORA.

package/docs/onChange.md

@@ -0,0 +1,318 @@
+# LDAP onChange Plugin
+
+Monitor LDAP attribute changes and trigger hooks for specific attributes.
+
+## Overview
+
+The `onChange` plugin watches for LDAP modifications and generates specialized hooks when configured attributes change. This enables reactive integrations with external systems (mail servers, quota managers, etc.).
+
+## Configuration
+
+```bash
+--plugin core/ldap/onChange \
+--mail-attribute mail \
+--quota-attribute mailQuota
+```
+
+**Environment Variables:**
+
+```bash
+DM_MAIL_ATTRIBUTE="mail"
+DM_QUOTA_ATTRIBUTE="mailQuota"
+```
+
+## Generated Hooks
+
+The plugin generates hooks based on configured attributes:
+
+| Config Parameter    | Generated Hook      | Parameters                       |
+| ------------------- | ------------------- | -------------------------------- |
+| `--mail-attribute`  | `onLdapMailChange`  | `(dn, oldMail, newMail)`         |
+| `--quota-attribute` | `onLdapQuotaChange` | `(dn, mail, oldQuota, newQuota)` |
+
+Generic hook for any change:
+
+- `onLdapChange` - `(dn, changes)` where `changes` is `Record<attr, [oldValue, newValue]>`
+
+## How It Works
+
+1. **Hooks into LDAP modify operations** via `ldapUsersmodify` and `ldapGroupsmodify` hooks
+2. **Detects attribute changes** by comparing old and new values
+3. **Triggers specialized hooks** for configured attributes
+4. **Provides old and new values** to downstream hooks
+
+## Use Cases
+
+### Mail Server Synchronization
+
+When user email changes, update external mail server:
+
+```javascript
+// In another plugin
+hooks: {
+  onLdapMailChange: async (dn, oldMail, newMail) => {
+    await mailServer.renameAccount(oldMail, newMail);
+    console.log(`Renamed mail account: ${oldMail} → ${newMail}`);
+  };
+}
+```
+
+### Quota Management
+
+When quota changes, update mail server quota:
+
+```javascript
+hooks: {
+  onLdapQuotaChange: async (dn, mail, oldQuota, newQuota) => {
+    await mailServer.setQuota(mail, newQuota);
+    console.log(`Updated quota for ${mail}: ${oldQuota} → ${newQuota}`);
+  };
+}
+```
+
+### Generic Change Tracking
+
+Track all attribute changes:
+
+```javascript
+hooks: {
+  onLdapChange: async (dn, changes) => {
+    for (const [attr, [oldVal, newVal]] of Object.entries(changes)) {
+      console.log(`${dn}: ${attr} changed from ${oldVal} to ${newVal}`);
+    }
+  };
+}
+```
+
+## Examples
+
+### Example 1: Mail Attribute Monitoring
+
+```bash
+--plugin core/ldap/onChange \
+--plugin core/ldap/flatGeneric \
+--ldap-flat-schema ./schemas/users.json \
+--mail-attribute mail
+```
+
+When a user's mail attribute changes via API:
+
+```bash
+PUT /api/v1/ldap/users/jdoe
+{
+  "replace": {
+    "mail": "john.doe@newdomain.com"
+  }
+}
+```
+
+The `onLdapMailChange` hook fires with:
+
+- `dn`: `"uid=jdoe,ou=users,dc=example,dc=com"`
+- `oldMail`: `"jdoe@olddomain.com"`
+- `newMail`: `"john.doe@newdomain.com"`
+
+### Example 2: Multiple Attributes
+
+```bash
+--plugin core/ldap/onChange \
+--mail-attribute mail \
+--quota-attribute mailQuota
+```
+
+When both attributes change:
+
+```bash
+PUT /api/v1/ldap/users/jdoe
+{
+  "replace": {
+    "mail": "jdoe@company.com",
+    "mailQuota": "5000000000"
+  }
+}
+```
+
+Both hooks fire:
+
+1. `onLdapMailChange(dn, "old@mail.com", "jdoe@company.com")`
+2. `onLdapQuotaChange(dn, "jdoe@company.com", "1000000000", "5000000000")`
+
+### Example 3: Generic Change Listener
+
+```bash
+--plugin core/ldap/onChange
+```
+
+All modifications trigger `onLdapChange`:
+
+```bash
+PUT /api/v1/ldap/users/jdoe
+{
+  "replace": {
+    "cn": "John A. Doe",
+    "telephoneNumber": "+1234567890"
+  },
+  "delete": ["description"]
+}
+```
+
+Hook receives:
+
+```javascript
+{
+  "cn": ["John Doe", "John A. Doe"],
+  "telephoneNumber": [null, "+1234567890"],
+  "description": ["Old description", null]
+}
+```
+
+## Integration Examples
+
+### With Twake James Mail Server
+
+```bash
+--plugin core/ldap/onChange \
+--plugin twake/james \
+--plugin core/ldap/flatGeneric \
+--ldap-flat-schema ./schemas/twake/users.json \
+--mail-attribute mail \
+--quota-attribute mailQuota \
+--james-webadmin-url http://james:8000
+```
+
+The James plugin listens to `onLdapMailChange` and `onLdapQuotaChange` hooks and automatically updates the James mail server.
+
+### Custom Integration Plugin
+
+Create a custom plugin that reacts to changes:
+
+```typescript
+import DmPlugin from '../abstract/plugin';
+import { Hooks } from '../hooks';
+
+export default class CustomSync extends DmPlugin {
+  name = 'customSync';
+
+  dependencies = {
+    onChange: 'core/ldap/onChange',
+  };
+
+  hooks: Hooks = {
+    onLdapMailChange: async (dn, oldMail, newMail) => {
+      this.logger.info(`Mail changed: ${oldMail} → ${newMail}`);
+
+      try {
+        await fetch('https://api.example.com/update-email', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ dn, oldMail, newMail }),
+        });
+      } catch (err) {
+        this.logger.error(`Failed to sync mail change: ${err}`);
+      }
+    },
+  };
+}
+```
+
+## Change Detection
+
+### Replace Operations
+
+```javascript
+// Before: mail = "old@example.com"
+{
+  replace: {
+    mail: 'new@example.com';
+  }
+}
+// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", "old@example.com", "new@example.com")
+```
+
+### Add Operations
+
+```javascript
+// Before: mail = undefined
+{
+  add: {
+    mail: 'new@example.com';
+  }
+}
+// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", null, "new@example.com")
+```
+
+### Delete Operations
+
+```javascript
+// Before: mail = "old@example.com"
+{ delete: ["mail"] }
+// Triggers: onLdapMailChange("uid=user,ou=users,dc=example,dc=com", "old@example.com", null)
+```
+
+## Performance Considerations
+
+### Hook Execution
+
+- Hooks run **synchronously** within the modify operation
+- Slow hooks delay the LDAP response
+- Consider async operations with fire-and-forget for non-critical updates
+
+### Optimization Tips
+
+1. **Keep hooks fast**: Defer heavy work to background jobs
+2. **Use error handling**: Don't let hook failures block LDAP operations
+3. **Batch updates**: If possible, batch multiple hook calls
+4. **Cache external state**: Avoid redundant external API calls
+
+## Error Handling
+
+Hooks can throw errors to abort the LDAP modification:
+
+```javascript
+hooks: {
+  onLdapMailChange: async (dn, oldMail, newMail) => {
+    // Validate mail domain
+    if (!newMail.endsWith('@company.com')) {
+      throw new Error('Mail must be @company.com domain');
+    }
+
+    // Update mail server
+    try {
+      await mailServer.renameAccount(oldMail, newMail);
+    } catch (err) {
+      throw new Error(`Mail server update failed: ${err.message}`);
+    }
+  };
+}
+```
+
+If the hook throws, the LDAP modification is rolled back (if supported by LDAP server).
+
+## Debugging
+
+Enable debug logging to see change detection:
+
+```bash
+--log-level debug
+```
+
+Output:
+
+```
+[debug] Detected mail change for uid=jdoe,ou=users,dc=example,dc=com: old@domain.com → new@domain.com
+[debug] Triggering onLdapMailChange hook
+[info] onLdapMailChange: Mail account renamed successfully
+```
+
+## Limitations
+
+1. **Only monitors modify operations**: Does not detect changes from direct LDAP clients
+2. **Requires old value lookup**: Fetches entry before modification for comparison
+3. **Single-valued attributes**: Best suited for single-valued attributes like mail
+4. **Synchronous execution**: Hooks block the LDAP response
+
+## See Also
+
+- [Twake James Plugin](twakeJames.md) - Mail server integration using onChange
+- [ldapFlatGeneric.md](ldapFlatGeneric.md) - Generic LDAP entity management
+- [Hooks Documentation](../src/hooks.ts) - All available hooks