ldap-rest 0.4.7 → 0.6.0

package/docs/usage/plugins/integrations/app-accounts.md

@@ -43,8 +43,36 @@ Instead of using a single primary password to access all services that authentic
 2. **App accounts consistency plugin** `core/twake/appAccountsConsistency` - **Required**
    - Automatically creates principal accounts (uid=mail@domain.com)
    - Ensures automatic cleanup when users are deleted
-   - Synchronizes mail changes across all app accounts
+   - Moves the principal account on a mail change, and drops the app accounts:
+     every MUA has to be reconfigured against the new address anyway
 3. **Applicative accounts base** configured in LDAP (e.g., `ou=applicative,dc=example,dc=com`)
+4. **Read access on `userPassword`** in that branch, for the bind DN
+   (`--ldap-dn`) - **Required for deletion**
+
+   Revoking an app account means removing _its_ value from the principal
+   account, which holds one `userPassword` per device. The server must read the
+   stored hash to know which value to remove — a salted hash cannot be
+   recomputed. Without that access, `DELETE` returns `500` and keeps the
+   account rather than reporting a revocation that did not happen.
+
+   A typical OpenLDAP ACL, scoped to the applicative branch so that the users'
+   primary passwords stay unreadable:
+
+   ```
+   olcAccess: to dn.subtree="ou=applicative,dc=example,dc=com" attrs=userPassword
+     by dn.exact="cn=ldap-rest,ou=tech,dc=example,dc=com" read
+     by * break
+   ```
+
+   It must precede any broader rule on `userPassword`; OpenLDAP stops at the
+   first matching directive, and `by * break` lets other identities fall
+   through to the following ones.
+
+5. **Uniqueness constraints must not cover the applicative branch.** The
+   principal account and its app accounts intentionally share the same `mail`,
+   so a `slapo-unique` overlay on `mail` has to be scoped to the users branch
+   (`olcUniqueURI: ldap:///ou=users,dc=example,dc=com?mail?sub?`) or every app
+   account creation is rejected.
 
 ## Configuration
 
@@ -181,6 +209,8 @@ Content-Type: application/json
 - `400 Bad Request` - Max accounts limit reached or user has no mail
 - `401 Unauthorized` - Missing or invalid token
 - `404 Not Found` - User not found
+- `500 Internal Server Error` - The password could not be added to the principal
+  account; the app account is rolled back and no password is returned
 
 ### Delete Applicative Account
 
@@ -202,6 +232,9 @@ Authorization: Bearer {token}
 - `200 OK` - Account deleted (or already deleted - idempotent)
 - `401 Unauthorized` - Missing or invalid token
 - `403 Forbidden` - UID does not belong to user
+- `500 Internal Server Error` - The account password could not be read, or could
+  not be removed from the principal account; the app account is kept so the
+  request stays replayable
 
 ## Password Generation
 
@@ -263,7 +296,7 @@ sync-app-accounts --help
    - Secure random password
 4. Plugin creates applicative account in LDAP:
    - `uid=alice_c12345678,ou=applicative,dc=example,dc=com`
-   - Copies attributes from user (cn, sn, mail, etc.)
+   - Copies the allowlisted attributes from the user (`--applicative-account-attribute`)
    - Sets generated password
 5. Plugin adds password to principal account:
    - `uid=alice@example.com,ou=applicative,dc=example,dc=com`

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

@@ -14,6 +14,7 @@ Plugins for LDAP entity management.
 | [external-users](external-users.md)   | Contacts                 | Automatic creation                  |
 | [on-change](on-change.md)             | All                      | Change detection                    |
 | [password-policy](password-policy.md) | Password management      | Expiration, Lockout, Unlock         |
+| [raw](raw.md)                         | Whole directory (read)   | Root DSE, Schema, Tree, Raw search  |
 
 ## API Endpoints
 
@@ -62,6 +63,17 @@ GET    /api/v1/password-policy/locked-accounts  # List locked accounts
 POST   /api/v1/password/validate                # Validate complexity (optional)
 ```
 
+### Low-level browsing (ldapRaw)
+
+```
+GET    /api/v1/ldap/raw/bases              # Exposed subtrees
+GET    /api/v1/ldap/raw/rootdse            # Server capabilities
+GET    /api/v1/ldap/raw/schema             # Parsed directory schema
+GET    /api/v1/ldap/raw/entry/{dn}         # Read one entry
+GET    /api/v1/ldap/raw/children/{dn}      # Direct children of an entry
+GET    /api/v1/ldap/raw/search             # Raw search (base, scope, filter)
+```
+
 ### Bulk Import (ldapBulkImport)
 
 ```

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

@@ -0,0 +1,226 @@
+# LDAP Raw Plugin (low-level browsing)
+
+Read-only, low-level access to the directory itself: root DSE, schema, and entries addressed by their DN. Where the other LDAP plugins expose business objects (users, groups, organizations), this one exposes the tree as it is stored — the server side of a phpLDAPadmin-like interface.
+
+The companion browser library is [`ldap-browser`](../../../client-development/browser/libraries.md#ldapbrowser).
+
+## Features
+
+- **Root DSE**: naming contexts, supported controls and extensions
+- **Schema**: object classes, attribute types, syntaxes and matching rules, parsed from the subschema entry (RFC 4512) and cached
+- **Entry read**: every attribute, operational ones included, binary values base64-encoded
+- **Tree navigation**: direct children of a DN, with an optional "has children" probe
+- **Raw search**: arbitrary base, scope and LDAP filter
+- **Read-only**: this plugin registers no write route
+
+## Configuration
+
+### Environment Variables
+
+- `DM_LDAP_RAW_BASE`: comma-separated subtrees to expose (default: `--ldap-base`)
+- `DM_LDAP_RAW_HIDDEN_ATTRIBUTES`: comma-separated attributes never returned, on top of the credential ones (default: none)
+- `DM_LDAP_RAW_SHOW_SECRETS`: serve credential attributes instead of hiding them (default: `false`)
+- `DM_LDAP_RAW_MAX_RESULTS`: maximum entries returned by a search or a children listing (default: `200`)
+- `DM_LDAP_RAW_SCHEMA_CACHE_TTL`: schema cache lifetime in seconds (default: `3600`)
+
+### Command Line
+
+```bash
+ldap-rest \
+  --plugin core/ldap/raw \
+  --ldap-raw-base "ou=users,dc=example,dc=com" \
+  --ldap-raw-base "ou=groups,dc=example,dc=com" \
+  --ldap-raw-hidden-attribute employeeNumber \
+  --ldap-raw-max-results 500
+```
+
+With no `--ldap-raw-base`, the plugin exposes `--ldap-base`.
+
+## API Endpoints
+
+```
+GET /api/v1/ldap/raw/bases          # Exposed subtrees (roots of the tree)
+GET /api/v1/ldap/raw/rootdse        # Server capabilities
+GET /api/v1/ldap/raw/schema         # Parsed directory schema
+GET /api/v1/ldap/raw/entry/{dn}     # One entry, operational attributes included
+GET /api/v1/ldap/raw/children/{dn}  # Direct children of an entry
+GET /api/v1/ldap/raw/search         # Arbitrary search
+```
+
+`{dn}` is the URL-encoded fully-qualified DN.
+
+### Entry format
+
+Attribute values are always arrays. A `binary` flag tells whether the values are base64-encoded octets rather than text:
+
+```json
+{
+  "dn": "uid=alice,ou=users,dc=example,dc=com",
+  "attributes": {
+    "objectClass": { "values": ["top", "inetOrgPerson"], "binary": false },
+    "uid": { "values": ["alice"], "binary": false },
+    "cn": { "values": ["Alice Smith"], "binary": false },
+    "jpegPhoto": { "values": ["/9j/4AAQSkZJRg…"], "binary": true }
+  }
+}
+```
+
+A value is flagged binary when the directory returned octets that are not valid UTF-8, or when the attribute type is binary.
+
+Credential attributes are **not** part of the response by default — see [Hidden attributes](#hidden-attributes).
+
+### Children
+
+```bash
+curl "$URL/api/v1/ldap/raw/children/$(urlencode 'dc=example,dc=com')?children=1"
+```
+
+```json
+{
+  "children": [
+    {
+      "dn": "ou=users,dc=example,dc=com",
+      "rdn": "ou=users",
+      "objectClass": ["organizationalUnit"],
+      "hasChildren": true
+    }
+  ],
+  "truncated": false
+}
+```
+
+`hasChildren` is only computed when the `children` query parameter is set: it costs one extra search per child.
+
+At most `--ldap-raw-max-results` children are returned. `truncated` is true when the branch holds more, so a browsing UI can say so instead of silently showing a partial list — a branch of 5000 users must not look like a branch of 200.
+
+### Search
+
+| Parameter    | Default                  | Description                                    |
+| ------------ | ------------------------ | ---------------------------------------------- |
+| `base`       | first exposed base       | Search base, must be inside an exposed subtree |
+| `scope`      | `sub`                    | `base`, `one` or `sub`                         |
+| `filter`     | `(objectClass=*)`        | LDAP filter                                    |
+| `attributes` | `*`                      | Comma-separated attribute list                 |
+| `limit`      | `--ldap-raw-max-results` | Capped by `--ldap-raw-max-results`             |
+
+```bash
+curl "$URL/api/v1/ldap/raw/search?base=ou=users,dc=example,dc=com&filter=(mail=*@example.com)&attributes=uid,mail"
+```
+
+```json
+{ "entries": [...], "truncated": false }
+```
+
+`truncated` is true when the limit cut the result set short.
+
+The filter is parsed before the search runs, so a malformed one comes back as a 400 naming it rather than as a server error — a search box receives whatever the user typed, and `gov` is a typo, not a server fault:
+
+```json
+{
+  "error": "Invalid LDAP filter \"gov\": Invalid expression: gov. A filter must be parenthesised, e.g. (cn=foo) or (|(cn=*foo*)(ou=*foo*))"
+}
+```
+
+### Schema
+
+```json
+{
+  "objectClasses": [
+    {
+      "oid": "2.5.6.6",
+      "names": ["person"],
+      "desc": "RFC2256: a person",
+      "kind": "STRUCTURAL",
+      "sup": ["top"],
+      "must": ["sn", "cn"],
+      "may": ["userPassword", "telephoneNumber", "seeAlso", "description"],
+      "obsolete": false
+    }
+  ],
+  "attributeTypes": [
+    {
+      "oid": "2.5.4.3",
+      "names": ["cn", "commonName"],
+      "sup": "name",
+      "singleValue": false,
+      "noUserModification": false,
+      "usage": "userApplications",
+      "obsolete": false,
+      "collective": false
+    }
+  ],
+  "syntaxes": [...],
+  "matchingRules": [...]
+}
+```
+
+Inheritance is **not** flattened: a client resolving the attributes of an entry must walk the `sup` chains. `SchemaView` (browser) and `SchemaIndex` (`src/lib/ldapSchema.ts`, server) do it for you.
+
+## Hidden attributes
+
+Attributes holding credential material are stripped from **every** response — entry reads and searches alike — before it leaves the server. Asking for one explicitly (`?attributes=uid,userPassword`) does not get around the filter: the removal happens when the entry is serialised, not when the query is built.
+
+The built-in list covers the usual OpenLDAP, Samba, Kerberos and Active Directory spellings:
+
+```
+userPassword, authPassword, pwdHistory, sambaNTPassword, sambaLMPassword,
+sambaPasswordHistory, krbPrincipalKey, krbExtraData, krbPwdHistory,
+unicodePwd, dbcsPwd, lmPwdHistory, ntPwdHistory, supplementalCredentials,
+userPKCS12
+```
+
+A password hash served over HTTP is an offline cracking target, and browsing a directory does not require reading one — hence hidden by default, visible only on request:
+
+```bash
+--ldap-raw-show-secrets true    # logs a warning at startup
+```
+
+Site-specific attributes are added with `--ldap-raw-hidden-attribute`, which stacks on top of the built-in list rather than replacing it:
+
+```bash
+--ldap-raw-hidden-attribute twakeApiKey --ldap-raw-hidden-attribute employeeNumber
+```
+
+Note that hiding an attribute here keeps it out of the API, not out of the directory: an account able to bind to LDAP directly still reads it. This is a guard against casual exposure through the browsing UI, not an access control — use [authz-per-branch](../auth/authz-per-branch.md) or directory ACLs for that.
+
+## Security
+
+Access is restricted in three independent layers:
+
+1. **Exposed bases** — any DN outside `--ldap-raw-base` is refused with a 403, whatever the caller's rights.
+2. **Authorization hooks** — every entry read, children listing and search goes through `server.ldap`, so the authorization plugins ([authz-per-branch](../auth/authz-per-branch.md), authz-dynamic, …) apply exactly as on the high-level APIs.
+3. **Hidden attributes** — credential attributes, plus anything in `--ldap-raw-hidden-attribute`, are removed from every response, including searches. See [Hidden attributes](#hidden-attributes).
+
+Two exceptions, both deliberate: the **root DSE** and the **schema** are read with the service account, not with the caller's rights. They are directory metadata and carry no user data; reading them with a restricted account would leave the UI unable to name and type attributes. Do not expose this plugin publicly if your directory publishes sensitive information in its root DSE.
+
+Combine with an authentication plugin ([token](../auth/token.md), [oidc](../auth/oidc.md), …) — this plugin adds no authentication of its own.
+
+## How It Works
+
+- **Schema fetch**: the root DSE is read for `subschemaSubentry` (falling back to `cn=Subschema`), then the subschema entry is fetched and parsed once per `--ldap-raw-schema-cache-ttl`. Concurrent callers share a single fetch.
+- **Operational attributes**: entries are read with `*` and `+`. When the server rejects `+`, the read is retried with `*` alone.
+- **Missing entries**: the LDAP "no such object" result (code 32) is mapped to a 404.
+
+## Limitations
+
+- **Read-only.** Creating, modifying, renaming and deleting entries is not exposed yet.
+- **No LDIF** import or export.
+- **No paging**: searches and children listings are capped by `--ldap-raw-max-results` and flagged as `truncated`; there is no cursor to fetch the rest. Use a narrower search to reach entries beyond the cap.
+
+## Usage Example
+
+```bash
+ldap-rest \
+  --plugin core/auth/token --auth-token "$TOKEN" \
+  --plugin core/ldap/raw \
+  --plugin core/static
+```
+
+The demo page ([`examples/web/ldap-browser.html`](../../../../examples/web/ldap-browser.html)) is then served at
+`/static/examples/web/ldap-browser.html`.
+
+## See Also
+
+- [ldap-browser client library](../../../client-development/browser/libraries.md#ldapbrowser)
+- [organizations plugin](organizations.md) — high-level tree of organizational units
+- [authz-per-branch plugin](../auth/authz-per-branch.md) — branch-level access control

package/examples/web/README.md

@@ -82,6 +82,23 @@ Manage organizational units.
 - Move units
 - Create/delete units
 
+### 🗂️ LDAP Browser (`ldap-browser.html`)
+
+Low-level, read-only view of the directory, in the spirit of phpLDAPadmin.
+
+**Features:**
+
+- Lazy tree of the whole directory
+- Raw entry content, operational attributes included
+- Schema annotations: mandatory attributes, descriptions, unknown attributes flagged
+- LDAP filter search with scope selection
+
+Requires the `core/ldap/raw` plugin:
+
+```bash
+npm start -- --plugin core/ldap/raw
+```
+
 ## Running Examples
 
 1. **Start the server:**
@@ -109,6 +126,7 @@ Manage organizational units.
    http://localhost:8081/static/examples/web/ldap-user-editor.html
    http://localhost:8081/static/examples/web/ldap-group-editor.html
    http://localhost:8081/static/examples/web/ldap-unit-editor.html
+   http://localhost:8081/static/examples/web/ldap-browser.html
    ```
 
 ## Using Browser Libraries in Your Application

package/examples/web/ldap-browser.html

@@ -0,0 +1,94 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>LDAP Browser Demo</title>
+
+    <!-- Google Fonts -->
+    <link
+      href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"
+      rel="stylesheet"
+    />
+    <link
+      href="https://fonts.googleapis.com/icon?family=Material+Icons"
+      rel="stylesheet"
+    />
+
+    <!-- Shared CSS -->
+    <link rel="stylesheet" href="/static/browser/common-demo.css" />
+    <!-- Library CSS -->
+    <link rel="stylesheet" href="/static/browser/ldap-browser.css" />
+
+    <style>
+      :root {
+        --primary-color: #3949ab;
+        --primary-color-dark: #283593;
+      }
+
+      body {
+        background: linear-gradient(135deg, #8ea7e9 0%, #3949ab 100%);
+      }
+
+      .demo-header h1 {
+        color: #3949ab;
+      }
+
+      #ldap-browser {
+        height: 70vh;
+        min-height: 520px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="demo-container">
+      <div class="demo-header">
+        <h1>🗂️ LDAP Browser</h1>
+        <p>
+          Low-level, read-only view of the directory: tree, raw entries and
+          schema
+        </p>
+      </div>
+
+      <div id="status-container"></div>
+
+      <div id="ldap-browser"></div>
+    </div>
+
+    <!-- Shared utilities -->
+    <script src="/static/browser/shared.js"></script>
+    <!-- Library JS -->
+    <script src="/static/browser/ldap-browser.js"></script>
+
+    <script>
+      const { LdapBrowser } = window.LdapBrowser;
+      const { showStatus } = window.MiniDmShared;
+
+      async function initBrowser() {
+        try {
+          const browser = new LdapBrowser({
+            containerId: 'ldap-browser',
+            apiBaseUrl: window.location.origin,
+            onEntrySelected: dn => console.log('Entry selected:', dn),
+            onError: error => {
+              console.error('Browser error:', error);
+              showStatus(
+                'status-container',
+                `Error: ${error.message}`,
+                'error'
+              );
+            },
+          });
+
+          await browser.init();
+          showStatus('status-container', 'LDAP Browser loaded', 'success');
+        } catch (error) {
+          console.error('Failed to initialize browser:', error);
+          showStatus('status-container', `Error: ${error.message}`, 'error');
+        }
+      }
+
+      initBrowser();
+    </script>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.4.7",
+  "version": "0.6.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -132,6 +132,10 @@
       "types": "./dist/src/plugins/ldap/passwordPolicy.d.ts",
       "import": "./dist/plugins/ldap/passwordPolicy.js"
     },
+    "./plugin-ldap-raw": {
+      "types": "./dist/src/plugins/ldap/raw.d.ts",
+      "import": "./dist/plugins/ldap/raw.js"
+    },
     "./plugin-ldap-trash": {
       "types": "./dist/src/plugins/ldap/trash.d.ts",
       "import": "./dist/plugins/ldap/trash.js"
@@ -232,6 +236,34 @@
       "types": "./dist/src/abstract/twakePlugin.d.ts",
       "import": "./dist/abstract/twakePlugin.js"
     },
+    "./browser-ldap-browser-ldapbrowser": {
+      "types": "./dist/src/browser/ldap-browser/LdapBrowser.d.ts",
+      "import": "./static/browser/ldap-browser/LdapBrowser.js"
+    },
+    "./browser-ldap-browser-api-rawapiclient": {
+      "types": "./dist/src/browser/ldap-browser/api/RawApiClient.d.ts",
+      "import": "./static/browser/ldap-browser/api/RawApiClient.js"
+    },
+    "./browser-ldap-browser-components-entrytree": {
+      "types": "./dist/src/browser/ldap-browser/components/EntryTree.d.ts",
+      "import": "./static/browser/ldap-browser/components/EntryTree.js"
+    },
+    "./browser-ldap-browser-components-entryview": {
+      "types": "./dist/src/browser/ldap-browser/components/EntryView.d.ts",
+      "import": "./static/browser/ldap-browser/components/EntryView.js"
+    },
+    "./browser-ldap-browser-index": {
+      "types": "./dist/src/browser/ldap-browser/index.d.ts",
+      "import": "./static/browser/ldap-browser/index.js"
+    },
+    "./browser-ldap-browser-schema": {
+      "types": "./dist/src/browser/ldap-browser/schema.d.ts",
+      "import": "./static/browser/ldap-browser/schema.js"
+    },
+    "./browser-ldap-browser-types": {
+      "types": "./dist/src/browser/ldap-browser/types.d.ts",
+      "import": "./static/browser/ldap-browser/types.js"
+    },
     "./browser-ldap-group-editor-ldapgroupeditor": {
       "types": "./dist/src/browser/ldap-group-editor/LdapGroupEditor.d.ts",
       "import": "./static/browser/ldap-group-editor/LdapGroupEditor.js"
@@ -578,6 +610,8 @@
     "check": "npm run check:ts && npm run lint && npm run format:check",
     "check:ts": "tsc --noEmit",
     "clean": "rimraf dist/* static/browser/* coverage",
+    "coverage": "c8 --config .c8rc.json mocha",
+    "coverage:check": "npm run check:ts && c8 --config .c8rc.json --exclude 'src/browser/**' --check-coverage --statements 84 --lines 84 --branches 75 --functions 86 mocha",
     "dev": "npm run start:dev",
     "fix": "npm run lint:fix && npm run format:fix",
     "format:check": "prettier --check .",
@@ -626,6 +660,7 @@
     "@types/supertest": "^6.0.3",
     "@typescript-eslint/eslint-plugin": "^8.44.0",
     "@typescript-eslint/parser": "^8.44.0",
+    "c8": "^10.1.3",
     "chai": "^6.0.1",
     "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",
@@ -633,6 +668,7 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^5.5.4",
     "fast-glob": "^3.3.3",
+    "globals": "^14.0.0",
     "js-yaml": "^4.1.1",
     "mocha": "^11.7.2",
     "nock": "^14.0.10",