ldap-rest 0.0.1 → 0.1.0

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

@@ -0,0 +1,58 @@
+/**
+ * App Accounts Consistency Plugin
+ *
+ * Automatically manages applicative account entries for protocol-based authentication
+ * (e.g., IMAP, SMTP, CalDAV, CardDAV).
+ *
+ * ## Concept
+ *
+ * Instead of using a single primary password for all services, this system separates:
+ * - **Primary authentication**: May use passwordless methods (smart cards, biometrics, SSO)
+ * - **Applicative accounts**: Dedicated accounts per device/application
+ *
+ * This is essential for protocols requiring password authentication (IMAP, SMTP, CalDAV)
+ * while maintaining security and allowing easy revocation per device.
+ *
+ * ## Behavior
+ *
+ * When a user with a mail attribute is created, this plugin creates a corresponding
+ * principal applicative account entry in a separate branch (e.g., ou=applicative).
+ *
+ * When a user is deleted, all corresponding applicative accounts are also deleted.
+ *
+ * When a user's mail changes, all applicative accounts are updated with the new mail.
+ */
+import DmPlugin from '../../abstract/plugin';
+import type { Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import { Hooks } from '../../hooks';
+export default class AppAccountsConsistency extends DmPlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        onLdapChange: string;
+    };
+    private mailAttr;
+    private applicativeAccountBase;
+    private operationalAttributes;
+    constructor(server: DM);
+    /**
+     * Check if an attribute should be excluded when copying LDAP entry attributes
+     * @param key - The attribute name to check
+     * @returns true if the attribute should be excluded
+     */
+    private shouldExcludeAttribute;
+    hooks: Hooks;
+    /**
+     * Create applicative account for a user
+     */
+    private createApplicativeAccount;
+    /**
+     * Delete applicative account by mail
+     */
+    private deleteApplicativeAccount;
+    /**
+     * Update applicative account when mail changes
+     */
+    private updateApplicativeAccount;
+}

package/docs/DEVELOPER_GUIDE.md

@@ -34,6 +34,7 @@ LDAP-Rest is a lightweight LDAP directory manager that provides:
 - **Schema-driven architecture** to adapt to different directory types (Twake, Active Directory, standard LDAP)
 - **Dynamic configuration** exposed via API
 - **Plugin-based extensibility** for custom functionality
+- **Robust error handling** ensuring server stability even when plugins encounter errors
 
 ### Architecture Overview
 

package/docs/PLUGIN_DEPENDENCIES.md

@@ -200,6 +200,25 @@ dependencies = {
 - **Consumes Hooks**: None
 - **Notes**: Synchronizes calendar resources with Twake Calendar
 
+#### `appAccountsConsistency` (twake/appAccountsConsistency)
+
+- **Dependencies**:
+  - `onLdapChange: 'core/ldap/onChange'` ⚠️ **Required**
+- **Provides Hooks**:
+  - `ldapadddone` - After user added, creates principal applicative account
+  - `onLdapMailChange` - When mail changes, updates applicative accounts
+- **Consumes Hooks**: (Hooks provided by `onLdapChange`)
+- **Notes**: Automatically creates and maintains principal applicative accounts (uid=mail)
+
+#### `appAccountsApi` (twake/appAccountsApi)
+
+- **Dependencies**:
+  - `authToken: 'core/auth/token'` ⚠️ **Required** (or another auth plugin)
+  - `appAccountsConsistency: 'core/twake/appAccountsConsistency'` ⚠️ **Required**
+- **Provides Hooks**: None
+- **Consumes Hooks**: None
+- **Notes**: RESTful API for managing applicative accounts (device/app-specific accounts). Depends on `appAccountsConsistency` for automatic cleanup and synchronization of app accounts.
+
 ### Utility Plugins
 
 #### `static` (core/static)

package/docs/README.md

@@ -77,6 +77,7 @@ If you want to extend LDAP-Rest with custom plugins, see below:
 
 - **[twakeJames](twakeJames.md)** - Apache James mail server synchronization
 - **[twakeCalendarResources](twakeCalendarResources.md)** - Twake Calendar resources synchronization
+- **[twakeAppAccountsApi](twakeAppAccountsApi.md)** - Applicative accounts API (device/app-specific accounts)
 
 ## Quick Start
 
@@ -134,67 +135,68 @@ ldap-rest \
 
 Plugins for managing different LDAP entity types:
 
-| Plugin            | Entity Type              | Features                                      |
-| ----------------- | ------------------------ | --------------------------------------------- |
-| ldapFlatGeneric   | Users, Positions, Custom | Schema-driven, Validation, Pointers           |
-| ldapGroups        | Groups                   | Member validation, Nested groups              |
-| ldapOrganizations | Organizational Units     | Tree navigation, Search                       |
-| ldapBulkImport    | Any (bulk operations)    | CSV import, Template generation, Multi-schema |
-| ldapTrash         | Any (soft delete)        | Trash system, Recovery, Metadata              |
+| Plugin                 | Entity Type              | Features                                      |
+| ---------------------- | ------------------------ | --------------------------------------------- |
+| core/ldap/flatGeneric  | Users, Positions, Custom | Schema-driven, Validation, Pointers           |
+| core/ldap/groups       | Groups                   | Member validation, Nested groups              |
+| core/ldap/organization | Organizational Units     | Tree navigation, Search                       |
+| core/ldap/bulkImport   | Any (bulk operations)    | CSV import, Template generation, Multi-schema |
+| core/ldap/trash        | Any (soft delete)        | Trash system, Recovery, Metadata              |
 
 ### Authentication
 
 Secure API access:
 
-| Plugin         | Type          | Use Case                     |
-| -------------- | ------------- | ---------------------------- |
-| token          | Bearer tokens | Development, APIs, Scripts   |
-| llng           | LemonLDAP::NG | Enterprise SSO               |
-| openidconnect  | OAuth2/OIDC   | Cloud identity, Social login |
-| authzPerBranch | Authorization | Branch-level access control  |
-| authzLinid1    | Authorization | LinID 1.x integration        |
+| Plugin                   | Type          | Use Case                     |
+| ------------------------ | ------------- | ---------------------------- |
+| core/auth/token          | Bearer tokens | Development, APIs, Scripts   |
+| core/auth/llng           | LemonLDAP::NG | Enterprise SSO               |
+| core/auth/openidconnect  | OAuth2/OIDC   | Cloud identity, Social login |
+| core/auth/authzPerBranch | Authorization | Branch-level access control  |
+| core/auth/authzLinid1    | Authorization | LinID 1.x integration        |
 
 ### Security
 
 Protection and rate limiting:
 
-| Plugin    | Type          | Use Case                      |
-| --------- | ------------- | ----------------------------- |
-| crowdsec  | IP blocking   | Block banned IPs via CrowdSec |
-| rateLimit | Rate limiting | Prevent brute-force attacks   |
+| Plugin              | Type          | Use Case                      |
+| ------------------- | ------------- | ----------------------------- |
+| core/auth/crowdsec  | IP blocking   | Block banned IPs via CrowdSec |
+| core/auth/rateLimit | Rate limiting | Prevent brute-force attacks   |
 
 ### Integration
 
 Connect to external systems:
 
-| Plugin                | Integrates With | Purpose              |
-| --------------------- | --------------- | -------------------- |
-| onChange              | Any             | Detect LDAP changes  |
-| twake/james           | Apache James    | Mail server sync     |
-| externalUsersInGroups | Groups          | Auto-create contacts |
+| Plugin                          | Integrates With | Purpose                  |
+| ------------------------------- | --------------- | ------------------------ |
+| core/ldap/onChange              | Any             | Detect LDAP changes      |
+| core/twake/james                | Apache James    | Mail server sync         |
+| core/twake/appAccountsApi       | LDAP            | App-specific account API |
+| core/ldap/externalUsersInGroups | Groups          | Auto-create contacts     |
 
 ### Utilities
 
 Support plugins:
 
-| Plugin  | Purpose               |
-| ------- | --------------------- |
-| static  | Serve web UI, schemas |
-| weblogs | Request logging       |
+| Plugin       | Purpose               |
+| ------------ | --------------------- |
+| core/static  | Serve web UI, schemas |
+| core/weblogs | Request logging       |
 
 ## Plugin Dependencies
 
 Some plugins require others:
 
 ```
-twake/james
+core/twake/james
   └─ requires: core/ldap/onChange
 
 core/ldap/externalUsersInGroups
   └─ requires: core/ldap/groups
 
 core/auth/authzPerBranch
-  └─ requires: Any authentication plugin (token, llng, openidconnect)
+  └─ requires: Any authentication plugin (core/auth/token, core/auth/llng, core/auth/openidconnect)
 ```
 
 ## Configuration
@@ -205,7 +207,7 @@ All CLI options can be set via environment variables:
 
 ```bash
 # LDAP connection
-export DM_LDAP_URL="ldap://localhost:389"
+export DM_LDAP_URL="ldap://localhost:389"  # or multiple URLs for failover
 export DM_LDAP_DN="cn=admin,dc=example,dc=com"
 export DM_LDAP_PWD="password"
 export DM_LDAP_BASE="dc=example,dc=com"
@@ -215,10 +217,45 @@ export DM_PLUGIN="core/auth/token,core/ldap/flatGeneric"
 export DM_AUTH_TOKENS="token1,token2"
 export DM_LDAP_FLAT_SCHEMA="./schemas/users.json"
 
+# Logging
+export DM_LOG_LEVEL="notice"  # error, warn, notice, info, debug
+
 # Start server
 ldap-rest
 ```
 
+### LDAP Failover
+
+LDAP-Rest supports multiple LDAP servers for high availability. Provide multiple URLs separated by commas:
+
+```bash
+# Command line
+--ldap-url ldap://ldap1.example.com,ldap://ldap2.example.com,ldap://ldap3.example.com
+
+# Or via environment variable
+export DM_LDAP_URL="ldap://ldap1.example.com,ldap://ldap2.example.com,ldap://ldap3.example.com"
+```
+
+The system will:
+1. Try to connect to each URL in order
+2. Use the first successful connection
+3. Automatically failover to the next URL if the current connection fails
+4. Log failover events for monitoring
+
+### Log Levels
+
+LDAP-Rest uses syslog-style log levels:
+
+```bash
+--log-level error   # Only errors
+--log-level warn    # Warnings and errors
+--log-level notice  # Web access logs (recommended for production)
+--log-level info    # General info + web logs + warnings + errors
+--log-level debug   # All messages including debug output
+```
+
+The **notice** level is ideal for production as it shows web access logs without flooding with general info messages.
+
 ### Configuration Files
 
 Use `.env` files or shell scripts:
@@ -439,6 +476,13 @@ Enable detailed logging:
 ldap-rest --log-level debug ...
 ```
 
+Available log levels (following syslog convention):
+- `error` - Only errors
+- `warn` - Warnings and errors
+- `notice` - Web access logs, warnings and errors (recommended for production)
+- `info` - General info messages, web logs, warnings and errors
+- `debug` - All messages including debug output
+
 ### Testing
 
 Run test suite: