ldap-rest 0.1.4 → 0.1.6

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

@@ -0,0 +1,136 @@
+# Token Authentication
+
+Simple stateless authentication using bearer tokens.
+
+## Configuration
+
+### Basic Configuration
+
+```bash
+--plugin core/auth/token \
+--auth-token "secret-token-1" \
+--auth-token "secret-token-2" \
+--auth-token "secret-token-3"
+```
+
+**Environment Variable:**
+
+```bash
+DM_AUTH_TOKENS="token1,token2,token3"
+```
+
+### Named Tokens (Recommended)
+
+Associate a descriptive name with each token for better logging and audit trails:
+
+```bash
+--plugin core/auth/token \
+--auth-token "9f8e7d6c5b4a:web-application" \
+--auth-token "1a2b3c4d5e6f:monitoring-service" \
+--auth-token "f1e2d3c4b5a6:backup-scripts"
+```
+
+**Environment Variable:**
+
+```bash
+DM_AUTH_TOKENS="9f8e7d6c5b4a:web-application,1a2b3c4d5e6f:monitoring-service,f1e2d3c4b5a6:backup-scripts"
+```
+
+**Syntax:** `token:name`
+
+- Token value comes first (the secret)
+- Colon `:` separator
+- Name comes second (descriptive identifier)
+
+## Usage
+
+Include the token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer 9f8e7d6c5b4a" \
+  http://localhost:8081/api/v1/ldap/users
+```
+
+## How It Works
+
+1. Extracts token from `Authorization: Bearer <token>` header
+2. Validates token against configured list
+3. Sets `req.user` to the token's name (e.g., `"web-application"`) or `"token {index}"` for unnamed tokens
+4. Returns 401 Unauthorized if token is missing or invalid
+
+**Named tokens in logs:**
+
+```
+INFO: Request from user: web-application
+INFO: Request from user: monitoring-service
+```
+
+**Unnamed tokens in logs (backward compatible):**
+
+```
+INFO: Request from user: token 0
+INFO: Request from user: token 1
+```
+
+## Use Cases
+
+- **Development/Testing**: Quick authentication without complex setup
+- **Service-to-Service**: API access for backend services
+- **CI/CD Pipelines**: Automated scripts and deployments
+- **Simple Deployments**: Small teams without SSO infrastructure
+
+## Security Considerations
+
+- Tokens are static and shared (not user-specific)
+- Use HTTPS in production to protect tokens in transit
+- Rotate tokens regularly
+- Limit token count to necessary services only
+- Consider combining with IP whitelisting
+
+## Example: Multiple Services with Named Tokens
+
+```bash
+# API server configuration with named tokens
+npx ldap-rest \
+  --plugin core/auth/token \
+  --auth-token "a1b2c3d4e5f6:production-web-app" \
+  --auth-token "f6e5d4c3b2a1:prometheus-monitoring" \
+  --auth-token "1234567890ab:nightly-backup" \
+  --ldap-url ldap://localhost:389 \
+  ...
+```
+
+```bash
+# Web application (logs will show: user: production-web-app)
+curl -H "Authorization: Bearer a1b2c3d4e5f6" \
+  http://api/v1/ldap/users
+
+# Monitoring system (logs will show: user: prometheus-monitoring)
+curl -H "Authorization: Bearer f6e5d4c3b2a1" \
+  http://api/v1/ldap/groups
+
+# Backup script (logs will show: user: nightly-backup)
+curl -H "Authorization: Bearer 1234567890ab" \
+  http://api/v1/ldap/organizations/top
+```
+
+## Example: Mixed Named and Unnamed Tokens
+
+You can mix named and unnamed tokens for backward compatibility:
+
+```bash
+--auth-token "abc123:production-api" \
+--auth-token "def456"  # Unnamed, will be "token 1" in logs \
+--auth-token "ghi789:staging-app"
+```
+
+## Troubleshooting
+
+**Problem:** 401 Unauthorized despite correct token
+
+**Solutions:**
+
+1. Ensure `Authorization: Bearer {token}` format (not just the token)
+2. Check token is in configured list
+3. Verify no whitespace in token
+4. Check server logs for token mismatch

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

@@ -0,0 +1,213 @@
+# TOTP Authentication
+
+Time-based One-Time Password (TOTP) authentication using dynamic codes compatible with authenticator apps.
+
+## Configuration
+
+### Basic Configuration
+
+```bash
+--plugin core/auth/totp \
+--auth-totp "JBSWY3DPEHPK3PXP:admin:6" \
+--auth-totp "HXDMVJECJJWSRB3H:service:8"
+```
+
+**Environment Variable:**
+
+```bash
+DM_AUTH_TOTP="JBSWY3DPEHPK3PXP:admin:6,HXDMVJECJJWSRB3H:service:8"
+```
+
+**Syntax:** `secret:name[:digits]`
+
+- **secret**: Base32-encoded secret (e.g., generated by authenticator apps)
+- **name**: Descriptive user/service name
+- **digits**: Number of digits in TOTP code (optional, 6-10, default: 6)
+
+### Advanced Configuration
+
+```bash
+--auth-totp-window 1    # Time window tolerance (±30s with step=30)
+--auth-totp-step 30     # Time step in seconds (default: 30)
+```
+
+**Environment Variables:**
+
+```bash
+DM_AUTH_TOTP_WINDOW=1   # Default: 1
+DM_AUTH_TOTP_STEP=30    # Default: 30
+```
+
+- **window**: Number of time steps to check before/after current time (compensates for clock drift)
+- **step**: Time interval in seconds for code generation (typically 30)
+
+## Generating Secrets
+
+Use an authenticator app or generate Base32 secrets:
+
+```bash
+# Using Node.js crypto (example)
+node -e "console.log(require('crypto').randomBytes(20).toString('base32'))"
+```
+
+## Usage
+
+### HTTP Requests
+
+Include the current TOTP code in the `Authorization` header:
+
+```bash
+# Get current TOTP code from your authenticator app
+curl -H "Authorization: Bearer 123456" \
+  http://localhost:8081/api/v1/ldap/users
+```
+
+### Browser Client
+
+The TOTP client library is available as an npm module export:
+
+```bash
+npm install ldap-rest
+```
+
+```typescript
+import {
+  TotpAuthClient,
+  generateTotp,
+  getRemainingSeconds,
+  isValidBase32,
+} from 'ldap-rest/browser-shared-utils-totp';
+
+const client = new TotpAuthClient({
+  secret: 'JBSWY3DPEHPK3PXP',
+  digits: 6,
+  step: 30,
+});
+
+// Automatic authentication with current TOTP code
+const response = await client.get('/api/v1/ldap/users');
+const users = await response.json();
+
+// Or get current code manually
+const code = await client.getCode();
+console.log(`Current TOTP code: ${code}`);
+```
+
+**Live Demo:** See [examples/web/totp-client.html](../../../../examples/web/totp-client.html) for an interactive demonstration.
+
+## How It Works
+
+1. Extracts TOTP code from `Authorization: Bearer <code>` header
+2. Generates expected TOTP codes for current time window
+3. Validates code against all configured users' secrets
+4. Supports multiple time windows (±window × step seconds) for clock drift tolerance
+5. Sets `req.user` to the user's name on successful validation
+6. Returns 401 Unauthorized if code is missing, invalid, or expired
+
+## Multi-User Example
+
+```bash
+# Configure multiple users with different code lengths
+--plugin core/auth/totp \
+--auth-totp "JBSWY3DPEHPK3PXP:admin:6" \
+--auth-totp "HXDMVJECJJWSRB3H:api-service:8" \
+--auth-totp "IXDMVJECJJWSRB2A:monitoring:10"
+```
+
+**In logs:**
+
+```
+INFO: TOTP authentication successful for user: admin
+INFO: TOTP authentication successful for user: api-service
+```
+
+## Use Cases
+
+- **Enhanced Security**: Dynamic codes that expire every 30 seconds
+- **No Shared Secrets**: Each user/service has unique TOTP secret
+- **Compatible**: Works with Google Authenticator, Authy, 1Password, etc.
+- **API Access**: Suitable for automated scripts with TOTP generation
+- **Multi-Factor**: Can be combined with other authentication methods
+
+## Security Considerations
+
+- **Secret Storage**: Store Base32 secrets securely (encrypted configuration, environment variables)
+- **HTTPS Required**: Always use HTTPS to protect TOTP codes in transit
+- **Clock Synchronization**: Ensure server and client clocks are synchronized (NTP recommended)
+- **Window Size**: Larger windows are more tolerant but slightly less secure
+- **Secret Rotation**: Rotate TOTP secrets periodically for better security
+- **Rate Limiting**: Consider adding rate limiting to prevent brute force attacks
+
+## Browser Client Features
+
+The TOTP browser library provides these functions and classes:
+
+```typescript
+import {
+  generateTotp,
+  getRemainingSeconds,
+  isValidBase32,
+  TotpAuthClient
+} from 'ldap-rest/browser-shared-utils-totp';
+
+// Generate TOTP code
+const code = await generateTotp({
+  secret: 'JBSWY3DPEHPK3PXP',
+  digits: 6,
+  step: 30
+});
+
+// Check validity time
+const remaining = getRemainingSeconds(30);
+console.log(`Code expires in ${remaining} seconds`);
+
+// Validate secret format
+if (isValidBase32('JBSWY3DPEHPK3PXP')) {
+  console.log('Valid Base32 secret');
+}
+
+// HTTP client with automatic TOTP authentication
+const client = new TotpAuthClient({
+  secret: 'JBSWY3DPEHPK3PXP',
+  digits: 6,
+  step: 30
+});
+
+// All HTTP methods automatically include TOTP in Authorization header
+await client.post('/api/v1/ldap/users', { uid: 'user1', ... });
+await client.put('/api/v1/ldap/users/user1', { mail: 'new@example.com' });
+await client.delete('/api/v1/ldap/users/user1');
+```
+
+**Module Export:** `ldap-rest/browser-shared-utils-totp`
+
+**Live Demo:** Run the server and open [http://localhost:8081/static/examples/web/totp-client.html](http://localhost:8081/static/examples/web/totp-client.html)
+
+## Troubleshooting
+
+**Problem:** 401 Unauthorized despite correct code
+
+**Solutions:**
+
+1. Verify secret is correctly configured (Base32 format)
+2. Check system clock synchronization (use NTP)
+3. Increase `--auth-totp-window` if experiencing timing issues
+4. Ensure code is used immediately (codes expire every 30s)
+5. Verify `Authorization: Bearer {code}` format
+
+**Problem:** Codes don't match authenticator app
+
+**Solutions:**
+
+1. Verify secret matches exactly (case-sensitive Base32)
+2. Check `--auth-totp-step` matches app configuration (usually 30)
+3. Ensure both server and device clocks are synchronized
+4. Confirm correct number of digits configured
+
+**Problem:** Invalid Base32 secret warning
+
+**Solutions:**
+
+1. Secret must contain only A-Z and 2-7 characters
+2. Use proper Base32 encoding (not Base64)
+3. Remove padding `=` characters if present (optional)

package/docs/usage/plugins/auth/trusted-proxy.md

@@ -0,0 +1,127 @@
+# Trusted Proxy
+
+When running behind a reverse proxy (nginx, Apache, HAProxy, etc.), client IP addresses are typically passed via `X-Forwarded-For` headers. The `trustedProxy` plugin validates these headers to prevent IP spoofing attacks.
+
+## Configuration
+
+```bash
+--plugin core/auth/trustedProxy \
+--trusted-proxy "127.0.0.1" \
+--trusted-proxy "10.0.0.0/8" \
+--trusted-proxy "192.168.0.0/16"
+```
+
+**Environment Variables:**
+
+```bash
+# Comma-separated list of trusted proxy IPs or CIDR ranges
+DM_TRUSTED_PROXIES="127.0.0.1,10.0.0.0/8,192.168.0.0/16,::1"
+
+# Optional: Header name for authenticated user from proxy (default: Auth-User)
+DM_TRUSTED_PROXY_AUTH_HEADER="Auth-User"
+```
+
+## How It Works
+
+1. **Request arrives** from reverse proxy
+2. **Plugin checks** if `req.socket.remoteAddress` matches a trusted proxy
+3. **If trusted:**
+   - `X-Forwarded-For` header is preserved
+   - `Auth-User` header (or custom header) is extracted for logging
+   - Request is marked as `req.trustedProxy = true`
+4. **If untrusted:**
+   - `X-Forwarded-For` header is **removed** to prevent IP spoofing
+   - Request is marked as `req.trustedProxy = false`
+5. **Other plugins** (rate limiting, CrowdSec, weblogs) see sanitized headers
+
+## Supported Formats
+
+- **IPv4 addresses:** `192.168.1.1`
+- **IPv6 addresses:** `::1`, `fe80::1`
+- **CIDR ranges:** `10.0.0.0/8`, `192.168.0.0/16`, `2001:db8::/32`
+- **IPv4-mapped IPv6:** Automatically handled (e.g., `::ffff:127.0.0.1` matches `127.0.0.1`)
+
+## Auth-User Header
+
+When requests come from a trusted proxy, the plugin can extract an authenticated username from a header set by the proxy. This is useful for:
+
+- Logging who made the request (even if LDAP-Rest doesn't handle authentication)
+- Passing identity from an upstream authentication system
+
+```bash
+# Custom header name (default: Auth-User)
+DM_TRUSTED_PROXY_AUTH_HEADER="X-Remote-User"
+```
+
+The extracted username is:
+
+- Available as `req.proxyAuthUser` for other plugins
+- Used by the `weblogs` plugin to log the user field
+
+## Example: nginx Configuration
+
+```nginx
+upstream ldap_rest {
+    server 127.0.0.1:8081;
+}
+
+server {
+    listen 443 ssl;
+    server_name api.example.com;
+
+    location / {
+        proxy_pass http://ldap_rest;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Optional: Pass authenticated user from nginx auth
+        proxy_set_header Auth-User $remote_user;
+    }
+}
+```
+
+LDAP-Rest configuration:
+
+```bash
+DM_TRUSTED_PROXIES="127.0.0.1"
+```
+
+## Example: HAProxy Configuration
+
+```haproxy
+frontend https
+    bind *:443 ssl crt /etc/ssl/cert.pem
+    default_backend ldap_rest
+
+backend ldap_rest
+    option forwardfor
+    http-request set-header X-Forwarded-Proto https
+    server ldap_rest 127.0.0.1:8081
+```
+
+## Use Cases
+
+- **Reverse Proxy Deployments:** Ensure correct client IP for rate limiting and logging
+- **Load Balancers:** Trust headers from known load balancer IPs
+- **CDN Integration:** Trust headers from CDN edge servers
+- **Kubernetes:** Trust headers from ingress controllers
+- **Security:** Prevent attackers from spoofing `X-Forwarded-For` to bypass rate limits
+
+## Security Considerations
+
+- **Only trust known proxies:** Never use `0.0.0.0/0` or trust all IPs
+- **Use specific IPs/ranges:** Limit to your actual proxy infrastructure
+- **HTTPS between proxy and LDAP-Rest:** Prevent header injection attacks
+- **Monitor logs:** Watch for warnings about removed X-Forwarded-For headers
+
+## Plugin Load Order
+
+The `trustedProxy` plugin is automatically loaded **first** (via `priority.json`) to ensure all other plugins see sanitized headers:
+
+1. `core/auth/trustedProxy` - Sanitizes X-Forwarded-For headers
+2. `core/weblogs` - Logs requests with correct client IP
+3. `core/auth/crowdsec` - Checks IP reputation
+4. `core/auth/rateLimit` - Rate limits by IP
+5. Authentication plugins...

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

@@ -0,0 +1,42 @@
+# Integration Plugins
+
+Plugins for connecting LDAP-Rest to external systems.
+
+## Apache James
+
+| Plugin                                | Description                     |
+| ------------------------------------- | ------------------------------- |
+| [james-mail](james-mail.md)           | User and domain synchronization |
+| [james-mailboxes](james-mailboxes.md) | Team mailbox management         |
+
+## Twake
+
+| Plugin                                      | Description                              |
+| ------------------------------------------- | ---------------------------------------- |
+| [calendar-resources](calendar-resources.md) | Calendar resource synchronization        |
+| [app-accounts](app-accounts.md)             | Applicative accounts API (devices, apps) |
+
+## Prerequisites
+
+### Apache James
+
+James plugins require:
+
+- Apache James running
+- WebAdmin URL configuration
+- James authentication token
+
+```bash
+--james-webadmin-url "http://localhost:8000"
+--james-token "your-james-token"
+```
+
+### Dependencies
+
+```
+core/twake/james
+  └─ requires: core/ldap/onChange
+
+core/twake/calendarResources
+  └─ requires: core/ldap/onChange
+```

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

@@ -0,0 +1,79 @@
+# LDAP Plugins
+
+Plugins for LDAP entity management.
+
+## Overview
+
+| Plugin                              | Entity                   | Features                            |
+| ----------------------------------- | ------------------------ | ----------------------------------- |
+| [flat-generic](flat-generic.md)     | Users, Positions, Custom | Schema-driven, Validation, Pointers |
+| [groups](groups.md)                 | Groups                   | Member validation, Nested groups    |
+| [organizations](organizations.md)   | Organizational Units     | Tree navigation, Search             |
+| [bulk-import](bulk-import.md)       | All (bulk operations)    | CSV import, Template generation     |
+| [trash](trash.md)                   | All (soft delete)        | Trash system, Recovery              |
+| [external-users](external-users.md) | Contacts                 | Automatic creation                  |
+| [on-change](on-change.md)           | All                      | Change detection                    |
+
+## API Endpoints
+
+### Entity Management (ldapFlatGeneric)
+
+```
+GET    /api/v1/ldap/{pluralName}           # List entries
+GET    /api/v1/ldap/{pluralName}/{id}      # Get entry
+POST   /api/v1/ldap/{pluralName}           # Create entry
+PUT    /api/v1/ldap/{pluralName}/{id}      # Modify entry
+DELETE /api/v1/ldap/{pluralName}/{id}      # Delete entry
+```
+
+### Groups (ldapGroups)
+
+```
+GET    /api/v1/ldap/groups                 # List groups
+GET    /api/v1/ldap/groups/{cn}            # Get group
+POST   /api/v1/ldap/groups                 # Create group
+PUT    /api/v1/ldap/groups/{cn}            # Modify group
+POST   /api/v1/ldap/groups/{cn}/rename     # Rename group
+POST   /api/v1/ldap/groups/{cn}/move       # Move group
+DELETE /api/v1/ldap/groups/{cn}            # Delete group
+```
+
+### Organizations (ldapOrganizations)
+
+```
+GET    /api/v1/ldap/organizations/top                    # Root organization
+GET    /api/v1/ldap/organizations/{dn}/subnodes         # Sub-organizations
+GET    /api/v1/ldap/organizations/{dn}/subnodes/search  # Search
+POST   /api/v1/ldap/organizations                       # Create
+PUT    /api/v1/ldap/organizations/{dn}                  # Modify
+POST   /api/v1/ldap/organizations/{dn}/move             # Move
+DELETE /api/v1/ldap/organizations/{dn}                  # Delete
+```
+
+### Bulk Import (ldapBulkImport)
+
+```
+GET    /api/v1/ldap/bulk-import/{resource}/template.csv  # CSV template
+POST   /api/v1/ldap/bulk-import/{resource}               # Import from CSV
+```
+
+## Schemas
+
+JSON schemas define the structure of LDAP entities.
+
+### Standard Schemas
+
+- `./static/schemas/standard/users.json` - inetOrgPerson users
+- `./static/schemas/standard/groups.json` - groupOfNames groups
+- `./static/schemas/standard/organizations.json` - Organizational units
+
+### Twake Schemas
+
+- `./static/schemas/twake/users.json` - Twake users
+- `./static/schemas/twake/groups.json` - Twake groups
+- `./static/schemas/twake/positions.json` - Positions/roles
+
+### Active Directory Schemas
+
+- `./static/schemas/ad/users.json` - AD accounts
+- `./static/schemas/ad/groups.json` - AD security groups

package/docs/usage/troubleshooting.md

@@ -0,0 +1,105 @@
+# Troubleshooting
+
+Guide for resolving common issues.
+
+## Connection Issues
+
+### Plugin not found
+
+**Symptom:** "Plugin not found" error at startup
+
+**Solutions:**
+
+1. Verify exact plugin name
+2. Use full path (e.g., `core/ldap/flatGeneric`)
+3. Check that plugin has no missing dependencies
+
+### LDAP connection failed
+
+**Symptom:** Unable to connect to LDAP server
+
+**Solutions:**
+
+1. Verify LDAP URL (`--ldap-url`)
+2. Verify bind DN (`--ldap-dn`)
+3. Verify password (`--ldap-pwd`)
+4. Test with `ldapsearch`:
+   ```bash
+   ldapsearch -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -b "dc=example,dc=com"
+   ```
+
+### Schema validation failed
+
+**Symptom:** Schema validation error
+
+**Solutions:**
+
+1. Verify JSON schema syntax
+2. Check required fields
+3. Enable debug for more details:
+   ```bash
+   --log-level debug
+   ```
+
+## API Issues
+
+### 404 on API endpoint
+
+**Symptom:** API endpoint returns 404
+
+**Solutions:**
+
+1. Verify that the plugin providing the endpoint is loaded
+2. Check exact endpoint URL
+3. Check logs for registered routes
+
+### 401 Unauthorized
+
+**Symptom:** Authentication refused
+
+**Solutions:**
+
+1. Verify `Authorization: Bearer {token}` header format
+2. Verify token is in configured list
+3. For TOTP, verify clock synchronization
+
+### 403 Forbidden
+
+**Symptom:** Access denied despite authentication
+
+**Solutions:**
+
+1. Check authorization rules (`authzPerBranch`)
+2. Verify IP is not blocked by CrowdSec
+3. Check logs for blocking reason
+
+## Debug Mode
+
+Enable detailed logging:
+
+```bash
+ldap-rest --log-level debug ...
+```
+
+Or via environment variable:
+
+```bash
+DM_LOG_LEVEL=debug ldap-rest
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# All tests
+source ~/.test-env && npm run test:dev
+
+# Single file
+source ~/.test-env && npm run test:one test/path/to/file.test.ts
+```
+
+## Support
+
+- **Issues:** https://github.com/linagora/ldap-rest/issues
+- **Documentation:** https://github.com/linagora/ldap-rest/tree/master/docs