ldap-rest 0.2.2 → 0.3.1

package/dist/src/plugins/static.d.ts

@@ -1,5 +1,38 @@
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../abstract/plugin';
+/**
+ * @openapi-component
+ * LdapSchema:
+ *   type: object
+ *   description: |
+ *     A JSON schema file served from the `schemas/` sub-directory of the
+ *     static path.  These schemas describe LDAP entity types (users, groups,
+ *     organizations, …) and are consumed by browser-embedded editors to
+ *     render attribute forms and validate input before submission.
+ *
+ *     The server replaces `__FOO_BAR__` placeholders on the fly with the
+ *     value of the corresponding `--foo-bar` CLI option so that a single
+ *     schema file can be shared between server-side validation and
+ *     client-side rendering.
+ *   additionalProperties: true
+ *   example:
+ *     entity:
+ *       name: standardUser
+ *       mainAttribute: uid
+ *       objectClass: [top, inetOrgPerson]
+ *       singularName: user
+ *       pluralName: users
+ *       base: ou=users,dc=example,dc=com
+ *     strict: true
+ *     attributes:
+ *       uid:
+ *         type: string
+ *         required: true
+ *         role: identifier
+ *       cn:
+ *         type: string
+ *         required: true
+ */
 export default class Static extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -1,6 +1,69 @@
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
+/**
+ * @openapi-component
+ * AppAccount:
+ *   type: object
+ *   description: |
+ *     An application-specific identity attached to a user.  App accounts
+ *     allow a single principal user to authenticate as different named
+ *     "devices" or "applications" each with its own credential, while
+ *     sharing the same mail address.
+ *   required: [uid]
+ *   properties:
+ *     uid:
+ *       type: string
+ *       description: |
+ *         Unique identifier of the app account.  Format:
+ *         `<username>_c<8-digits>` (e.g. `alice_c04729183`).
+ *       example: alice_c04729183
+ *     name:
+ *       type: string
+ *       description: Human-readable label (stored as LDAP `description`).
+ *       example: Work laptop
+ *   example:
+ *     uid: alice_c04729183
+ *     name: Work laptop
+ * AppAccountCreated:
+ *   type: object
+ *   description: |
+ *     Response returned when a new app account is successfully created.
+ *     The one-time cleartext password is included here and never returned
+ *     again — callers must store it immediately.
+ *   required: [uid, pwd, mail]
+ *   properties:
+ *     uid:
+ *       type: string
+ *       description: Identifier of the newly created app account.
+ *       example: alice_c04729183
+ *     pwd:
+ *       type: string
+ *       description: |
+ *         One-time cleartext password generated for this account.
+ *         Format: 6 blocks of 4 characters separated by `-`
+ *         (e.g. `Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@`).
+ *         OpenLDAP hashes it via ppolicy before storage.
+ *       example: Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@
+ *     mail:
+ *       type: string
+ *       description: Mail address of the principal account this app account belongs to.
+ *       example: alice@example.com
+ *   example:
+ *     uid: alice_c04729183
+ *     pwd: Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@
+ *     mail: alice@example.com
+ * AppAccountCreate:
+ *   type: object
+ *   description: Request body for creating a new app account.
+ *   properties:
+ *     name:
+ *       type: string
+ *       description: Optional human-readable label for the new account.
+ *       example: Work laptop
+ *   example:
+ *     name: Work laptop
+ */
 export default class AppAccountsApi extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -5,6 +5,53 @@ import type { DM } from '../../bin';
 import type { AttributeValue } from '../../lib/ldapActions';
 import { Hooks } from '../../hooks';
 import type { ChangesToNotify } from '../ldap/onChange';
+/**
+ * OpenAPI schemas specific to the James integration.
+ *
+ * @openapi-component
+ * JamesQuotaUsage:
+ *   type: object
+ *   description: |
+ *     Quota information for a mailbox user as returned by the James
+ *     WebAdmin API (`GET /quota/users/{mail}`). Contains separate
+ *     counters for message count and storage size.
+ *   properties:
+ *     count:
+ *       type: object
+ *       description: Message-count quota.
+ *       properties:
+ *         used:
+ *           type: integer
+ *           description: Number of messages currently stored.
+ *           example: 142
+ *         max:
+ *           type: integer
+ *           nullable: true
+ *           description: |
+ *             Maximum number of messages allowed. `null` means unlimited.
+ *           example: 10000
+ *     size:
+ *       type: object
+ *       description: Storage-size quota (bytes).
+ *       properties:
+ *         used:
+ *           type: integer
+ *           description: Bytes currently used.
+ *           example: 524288000
+ *         max:
+ *           type: integer
+ *           nullable: true
+ *           description: |
+ *             Maximum bytes allowed. `null` means unlimited.
+ *           example: 2147483648
+ *   example:
+ *     count:
+ *       used: 142
+ *       max: 10000
+ *     size:
+ *       used: 524288000
+ *       max: 2147483648
+ */
 export default class James extends TwakePlugin {
     name: string;
     roles: Role[];

package/docs/plugin-development/README.md

@@ -13,6 +13,7 @@ This guide will help you create powerful, production-ready plugins for LDAP-Rest
 - [Configuration Best Practices](#configuration-best-practices)
 - [Complete Plugin Example](#complete-plugin-example)
 - [Testing Your Plugin](#testing-your-plugin)
+- [Documenting REST endpoints (OpenAPI)](./openapi.md)
 
 ---
 
@@ -1282,7 +1283,7 @@ source ~/.test-env && npm run test:dev
 ## Additional Resources
 
 - [Contributing Guide](../../CONTRIBUTING.md) - Git workflow and PR guidelines
-- [Hooks Reference](../../HOOKS.md) - Complete list of available hooks
+- [Hooks Reference](./hooks.md) - Complete list of available hooks
 - [Core Plugin Examples](../../src/plugins/) - Browse existing plugins
 - [Test Examples](../../test/plugins/) - See how core plugins are tested
 

package/docs/plugin-development/openapi.md

@@ -0,0 +1,144 @@
+# Documenting plugin endpoints (OpenAPI)
+
+The published API reference at <https://linagora.github.io/ldap-rest/api/> is
+generated from `openapi.json`, which itself is built statically by
+[`scripts/generate-openapi.ts`](../../scripts/generate-openapi.ts) — it walks
+every plugin's `api()` method and reads the JSDoc comments above each route.
+
+You don't need to touch the generator to enrich your plugin's documentation.
+Two JSDoc directives drive the entire pipeline:
+
+- `@openapi` — placed **just above an `app.method(path, handler)` call**,
+  describes that single route.
+- `@openapi-component` — placed anywhere in the file, registers reusable
+  schemas under `components.schemas` so multiple routes can `$ref` them.
+
+Both directives carry inline **YAML** that follows the
+[OpenAPI 3.0 Operation Object](https://spec.openapis.org/oas/v3.0.3#operation-object)
+(or [Schema Object](https://spec.openapis.org/oas/v3.0.3#schema-object) for
+components). The generator parses the YAML and merges it on top of the
+defaults it would have emitted, so you only describe what you want to enrich.
+
+## Per-route metadata: `@openapi`
+
+```ts
+/**
+ * @openapi
+ * summary: Get group by CN
+ * description: |
+ *   The `:cn` segment may be either the group's RDN value or its full DN.
+ *   Returns the raw LDAP entry.
+ * responses:
+ *   '200':
+ *     description: Group entry.
+ *     content:
+ *       application/json:
+ *         schema: { $ref: '#/components/schemas/Group' }
+ *         example:
+ *           dn: cn=admins,ou=groups,dc=example,dc=com
+ *           cn: admins
+ *           description: Server administrators
+ *   '404':
+ *     description: Group not found.
+ */
+app.get(`${this.config.api_prefix}/v1/ldap/groups/:cn`, asyncHandler(...));
+```
+
+Anything below the `@openapi` line (up to the next `@directive` or the end of
+the JSDoc block) is YAML. The keys you provide override the auto-generated
+ones; everything you omit keeps the generator's defaults.
+
+### What you can override
+
+Any field of an OpenAPI Operation Object, including:
+
+| Field         | Notes                                                                            |
+| ------------- | -------------------------------------------------------------------------------- |
+| `summary`     | Short, one-line title.                                                           |
+| `description` | Long description (markdown).                                                     |
+| `tags`        | Array of strings; defaults to the plugin's tag.                                  |
+| `parameters`  | Concatenated with auto-generated path params (your entries win on duplicates).   |
+| `requestBody` | Replace the generic `application/json` placeholder with a real schema + example. |
+| `responses`   | Replace per status code.                                                         |
+| `security`    | List of security requirement objects (works as-is).                              |
+| `deprecated`  | `true` to mark the operation as deprecated.                                      |
+| `operationId` | Stable identifier for code generators.                                           |
+
+### What is autodetected
+
+The generator already extracts:
+
+- the **HTTP method** (`get`, `post`, …) from the call expression;
+- the **path** (substituting local `const prefix = ...` variables, the
+  `${this.config.api_prefix}` template, and a few well-known config knobs);
+- **path parameters** from `:param` segments;
+- a default **summary** built from the verb and the last path segment;
+- the plugin's **tag** (configured in `pluginTags` in the generator).
+
+So a minimal, correct `@openapi` block is often only two or three keys.
+
+## Reusable schemas: `@openapi-component`
+
+Place this anywhere in your plugin file (the convention is right above the
+class). The body is a YAML map of `<SchemaName>: <SchemaDefinition>` pairs:
+
+```ts
+/**
+ * @openapi-component
+ * Group:
+ *   type: object
+ *   required: [dn, cn]
+ *   properties:
+ *     dn: { type: string, example: cn=admins,ou=groups,dc=example,dc=com }
+ *     cn: { type: string, example: admins }
+ *     member:
+ *       type: array
+ *       items: { type: string }
+ * Error:
+ *   type: object
+ *   properties:
+ *     error: { type: string }
+ *     code: { type: integer }
+ */
+export default class LdapGroups extends DmPlugin {
+  // ...
+}
+```
+
+Refer to them from any route using `$ref`:
+
+```yaml
+schema: { $ref: '#/components/schemas/Group' }
+```
+
+Component names are global to the spec, so prefix them with the plugin's
+domain (`Group`, `ScimUser`, `PasswordPolicy`) to avoid collisions.
+
+## Tips
+
+- **Examples beat specs.** A single concrete `example:` block is worth a
+  dozen `description:` lines for someone trying the API for the first time.
+- **YAML alignment.** The generator strips the leading `*` from each line
+  before parsing, then dedents the block, so you can use any consistent
+  indentation as long as it's even within the block.
+- **Multiline strings.** Use YAML block scalars (`description: |`) for
+  paragraphs and code samples — they round-trip cleanly through Redoc.
+- **Annotation is opt-in.** Routes without an `@openapi` block are
+  **excluded** from the published spec — the generator prints a
+  `⚠️  Skipping undocumented route` warning so the author notices, but
+  the route does not surface in Redoc. The published doc therefore
+  reflects intentionally-documented API surface only, not every Express
+  call we happened to find.
+- **A plugin with zero annotated routes disappears entirely** from the
+  spec, by the same rule.
+
+## Regenerate locally
+
+```sh
+npm run generate:openapi   # writes openapi.json
+npm run build:pages        # rebuilds the static site under _site/
+```
+
+Open `_site/api/index.html` to preview the Redoc rendering. The published
+site at <https://linagora.github.io/ldap-rest/api/> is rebuilt automatically
+on every `v*` tag push.

package/docs/usage/plugins/auth/authz-dynamic.md

@@ -0,0 +1,183 @@
+# authzDynamic — LDAP-backed tokens + per-branch authorization
+
+The `authzDynamic` plugin combines **bearer-token authentication** and
+**per-branch authorization** in a single plugin, sourced entirely from a
+dedicated LDAP branch. Adding, rotating, or revoking a token — or changing its
+ACL — is a matter of writing to LDAP: no process restart, no config file.
+
+This is the recommended building block for multi-tenant deployments where
+each SCIM client (or REST API consumer) is scoped to its own subtree.
+
+## How it works
+
+1. The plugin loads all entries under `--authz-dynamic-base` and caches them.
+2. On every incoming request, it reads `Authorization: Bearer <token>` and
+   verifies the token against the `userPassword` hash of each cached entry
+   (timing-safe comparison).
+3. On a match, the plugin sets `req.user` to the tenant name and records the
+   token's ACL in an `AsyncLocalStorage` context.
+4. Downstream LDAP operations (via `ldapActions.search / add / modify / delete / rename`) trigger authz hooks that read the active token from the async context and throw if the requested DN is outside the allowed branches.
+5. The cache refreshes on a TTL (default 60 s) or on demand via a protected
+   reload endpoint.
+
+## Configuration
+
+```bash
+node lib/bin/index.js \
+  --ldap-url ldap://ldap.internal \
+  --ldap-base dc=example,dc=com \
+  --ldap-dn cn=admin,dc=example,dc=com --ldap-pwd '***' \
+  \
+  --plugin core/auth/authzDynamic \
+  --authz-dynamic-base ou=authz-tokens,dc=example,dc=com \
+  --authz-dynamic-cache-ttl 60 \
+  --authz-dynamic-reload-endpoint
+```
+
+### CLI / environment
+
+| Argument                           | Environment                         | Default        | Purpose                                                               |
+| ---------------------------------- | ----------------------------------- | -------------- | --------------------------------------------------------------------- |
+| `--authz-dynamic-base`             | `DM_AUTHZ_DYNAMIC_BASE`             | — (required)   | LDAP branch that contains the token entries                           |
+| `--authz-dynamic-cache-ttl`        | `DM_AUTHZ_DYNAMIC_CACHE_TTL`        | `60`           | Cache refresh interval in seconds                                     |
+| `--authz-dynamic-token-attribute`  | `DM_AUTHZ_DYNAMIC_TOKEN_ATTRIBUTE`  | `userPassword` | Attribute holding the hashed bearer token                             |
+| `--authz-dynamic-config-attribute` | `DM_AUTHZ_DYNAMIC_CONFIG_ATTRIBUTE` | `description`  | Attribute holding the JSON ACL document                               |
+| `--authz-dynamic-tenant-attribute` | `DM_AUTHZ_DYNAMIC_TENANT_ATTRIBUTE` | `cn`           | Attribute from which `req.user` is read                               |
+| `--authz-dynamic-reload-endpoint`  | `DM_AUTHZ_DYNAMIC_RELOAD_ENDPOINT`  | `false`        | Register `POST /api/v1/authz-dynamic/reload` for manual cache refresh |
+
+## Token entry shape
+
+Each token is a plain LDAP entry under `--authz-dynamic-base`. Minimal
+requirements: `cn` (token identifier), `userPassword` (the hashed secret),
+and a JSON ACL document in `description` (by default — override via
+`--authz-dynamic-config-attribute`).
+
+```ldif
+dn: cn=acme,ou=authz-tokens,dc=example,dc=com
+objectClass: top
+objectClass: inetOrgPerson
+cn: acme
+sn: acme
+userPassword: {SSHA}eFt2wP4ykczHzV9pzE3CH3k1t9M=
+description: {
+ "tenant": "acme",
+ "bases": [
+  { "dn": "ou=users,ou=acme,dc=example,dc=com",  "read": true, "write": true, "delete": true },
+  { "dn": "ou=groups,ou=acme,dc=example,dc=com", "read": true, "write": true, "delete": true }
+ ]
+}
+```
+
+### ACL JSON
+
+```json
+{
+  "tenant": "acme",
+  "bases": [
+    { "dn": "<branch DN>", "read": true, "write": true, "delete": true }
+  ]
+}
+```
+
+- **Sub-branch matching**: a permission on `ou=acme,dc=example,dc=com`
+  automatically covers `ou=users,ou=acme,…` and any sub-branch.
+- Absent flags default to `false`.
+- `tenant` is optional; if omitted, `req.user` falls back to the value of the
+  configured `tenantAttribute` (default `cn`).
+
+### Supported userPassword schemes
+
+Handled by a constant-time verifier (`authzDynamicHash.ts`):
+
+| Scheme                                | Notes                                                |
+| ------------------------------------- | ---------------------------------------------------- |
+| `{SSHA}`                              | salted SHA-1 — OpenLDAP default, recommended minimum |
+| `{SHA}`                               | unsalted SHA-1 — legacy                              |
+| `{SSHA256}` / `{SHA256}`              | salted / unsalted SHA-256                            |
+| `{SSHA512}` / `{SHA512}`              | salted / unsalted SHA-512                            |
+| `{SMD5}` / `{MD5}`                    | salted / unsalted MD5 — legacy, avoid                |
+| `{CLEARTEXT}` / `{PLAIN}` / no prefix | cleartext — test environments only                   |
+
+To generate an `{SSHA}` hash with OpenLDAP tools: `slappasswd -h '{SSHA}'`.
+To generate programmatically, `ssha(token)` is also exported from
+`authzDynamicHash.ts` for scripts.
+
+## Usage with SCIM
+
+This is the combination the plugin was designed for:
+
+```bash
+node lib/bin/index.js \
+  --ldap-base dc=example,dc=com \
+  --ldap-dn cn=admin,dc=example,dc=com --ldap-pwd '***' \
+  \
+  --plugin core/auth/authzDynamic \
+  --authz-dynamic-base ou=authz-tokens,dc=example,dc=com \
+  \
+  --plugin core/scim \
+  --scim-user-base-template  'ou=users,ou={user},dc=example,dc=com' \
+  --scim-group-base-template 'ou=groups,ou={user},dc=example,dc=com'
+```
+
+Each token's `tenant` field populates `req.user`, which the SCIM plugin uses
+to resolve its LDAP bases via the `{user}` template. Combined with the token's
+ACL, the client is cryptographically constrained to its own SCIM subtree.
+
+## Operational notes
+
+- **Cache**: read entries are kept in memory. A failed reload (LDAP hiccup)
+  keeps the previous snapshot in use — no request is ever served with an
+  empty cache unless the very first load fails.
+- **Reload endpoint**: when `--authz-dynamic-reload-endpoint` is set, any
+  **already-authenticated** token can call `POST /api/v1/authz-dynamic/reload`
+  to force an immediate refresh. Useful after provisioning a new token.
+- **Deletion**: deleting a token entry from LDAP invalidates it within
+  `--authz-dynamic-cache-ttl` seconds (or immediately if a reload is
+  triggered). Rotate compromised secrets this way.
+- **Audit**: every unauthorized attempt is logged at `warn` with a masked
+  token (first 8 chars + `...`). Every authorization failure is logged at
+  `error` via the DM error middleware.
+- **configApi**: when `core/configApi` is loaded, the plugin publishes a
+  compact status under `features.authzDynamic` (token count, base DN, cache
+  TTL, reload endpoint URL) — never hashes or per-token DNs.
+
+## Security considerations
+
+- **Secret storage**: always hash `userPassword` (`{SSHA}` or better). The
+  plugin refuses unknown scheme prefixes, but accepts cleartext — do not
+  deploy cleartext secrets in production.
+- **Timing**: comparisons run through `crypto.timingSafeEqual` or a buffer
+  wrapper, preventing timing oracles on the secret.
+- **Scope escape**: the authz hooks check every LDAP operation's DN against
+  the token's ACL. The active token is carried via `AsyncLocalStorage`, so it
+  applies even to plugins that do not thread `req` down to `ldapActions`.
+- **Binding credentials**: the DM bind user still has admin access — the
+  plugin's isolation is logical (path prefix check), not LDAP-layer ACL. For
+  a second layer of defence, configure OpenLDAP ACLs to match.
+
+## Example: listing a tenant's configuration
+
+With `core/configApi` loaded:
+
+```bash
+curl -H 'Authorization: Bearer <token>' http://localhost:8081/api/v1/config
+```
+
+The response contains (trimmed):
+
+```json
+{
+  "features": {
+    "authzDynamic": {
+      "enabled": true,
+      "base": "ou=authz-tokens,dc=example,dc=com",
+      "cacheTtlSeconds": 60,
+      "tokenCount": 17,
+      "tokenAttribute": "userPassword",
+      "configAttribute": "description",
+      "tenantAttribute": "cn",
+      "reloadEndpoint": "/api/v1/authz-dynamic/reload"
+    }
+  }
+}
+```