ldap-rest 0.3.0 → 0.3.2

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/configuration.md

@@ -27,6 +27,7 @@ All LDAP-Rest configuration options.
     - [core/auth/openidconnect](#coreauthopenidconnect)
   - [Authorization Plugins](#authorization-plugins)
     - [core/auth/authzPerBranch](#coreauthauthzperbranch)
+    - [core/auth/authzPerRoute](#coreauthauthzperroute)
     - [core/auth/authzLinid1](#coreauthauthzlinid1)
   - [Security Plugins](#security-plugins)
     - [core/auth/rateLimit](#coreauthratelimit)
@@ -236,6 +237,12 @@ Maintains consistency of department links when organizations are renamed/moved.
 | `--authz-per-branch-config`    | `DM_AUTHZ_PER_BRANCH_CONFIG`    | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON) |
 | `--authz-per-branch-cache-ttl` | `DM_AUTHZ_PER_BRANCH_CACHE_TTL` | `60`                                             | Cache TTL (seconds)         |
 
+#### `core/auth/authzPerRoute`
+
+| CLI                 | Env                   | Default | Description                                                            |
+| ------------------- | --------------------- | ------- | ---------------------------------------------------------------------- |
+| `--authz-per-route` | `DM_AUTHZ_PER_ROUTES` | `[]`    | Per-user route ACL rules (see [docs](plugins/auth/authz-per-route.md)) |
+
 #### `core/auth/authzLinid1`
 
 | CLI                             | Env                              | Default               | Description           |

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

@@ -17,6 +17,7 @@ LDAP-Rest provides multiple authentication plugins to secure API access. These p
 | Method                                          | Plugin                     | Description                 |
 | ----------------------------------------------- | -------------------------- | --------------------------- |
 | [Authorization Per Branch](authz-per-branch.md) | `core/auth/authzPerBranch` | Branch-level access control |
+| [Authorization Per Route](authz-per-route.md)   | `core/auth/authzPerRoute`  | HTTP route-level ACL        |
 | [Authorization LinID 1.x](authz-linid1.md)      | `core/auth/authzLinid1`    | LinID 1.x integration       |
 
 ## Security Plugins

package/docs/usage/plugins/auth/authz-per-route.md

@@ -0,0 +1,144 @@
+# Route-Level Authorization (`authzPerRoute`)
+
+Restricts access to specific HTTP routes based on the authenticated user's name
+(`req.user`), which is set by an auth plugin such as `core/auth/token`.
+
+This plugin complements `authzPerBranch` (LDAP-branch ACL) and `authzDynamic`
+(LDAP-backed tokens): whereas those operate at the LDAP-branch level,
+`authzPerRoute` works at the HTTP route level and needs no LDAP connection.
+
+## Plugin loading order
+
+`authzPerRoute` MUST run **after** the authentication plugin (so `req.user` is set)
+AND **before** any API route plugin (so its Express middleware is registered before
+the routes it protects).
+
+When loaded via the CLI plugin loader, plugins not listed in
+`src/plugins/priority.json` are loaded in parallel — this can race with API route
+registration and result in an authorization bypass. To guarantee correct ordering,
+`core/auth/authzPerRoute` is included in the priority list and loads sequentially
+after the other auth plugins. If you build a custom loader, ensure equivalent
+sequencing.
+
+```bash
+--plugin core/auth/token \
+--plugin core/auth/authzPerRoute
+```
+
+## Configuration
+
+### CLI
+
+```bash
+--authz-per-route "full-access:*" \
+--authz-per-route "updt-only:POST:/api/v1/ldap/updt" \
+--authz-per-route "updt-only:GET:/api/v1/ldap/updt/**"
+```
+
+### Environment Variable
+
+```bash
+DM_AUTHZ_PER_ROUTES="full-access:*,updt-only:POST:/api/v1/ldap/updt,updt-only:GET:/api/v1/ldap/updt/**"
+```
+
+Multiple values are comma-separated. Repeating `--authz-per-route` on the CLI
+is equivalent.
+
+## Rule Syntax
+
+Each entry has one of two forms:
+
+| Form                         | Meaning                                                     |
+| ---------------------------- | ----------------------------------------------------------- |
+| `<user>:*`                   | Full wildcard — allow any method on any path                |
+| `<user>:<METHOD>:<pathGlob>` | Allow only the given HTTP method on paths matching the glob |
+
+- `<user>` — the value of `req.user` as set by the auth plugin.
+- `<METHOD>` — an HTTP verb (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`,
+  `OPTIONS`) or `*` (any verb).
+- `<pathGlob>` — a glob pattern (not a regex). Patterns are implicitly
+  anchored start-to-end. Rules:
+  - `*` matches any sequence of characters **except** `/` (one path segment).
+  - `**` matches any sequence of characters **including** `/` (multiple segments).
+  - All other characters are matched literally — regex special characters (`.`, `+`,
+    `?`, etc.) have no special meaning.
+  - **Allowed characters:** alphanumerics (`a-z`, `A-Z`, `0-9`), `/`, `_`, `-`,
+    `.`, `+`, and `*`. Globs containing any other character (e.g. `;`, space,
+    `?`) are rejected at startup with a warning and the rule is skipped.
+
+A user may have multiple entries; access is granted if **any** rule matches
+(logical OR).
+
+### Examples
+
+```bash
+# admin token: full access
+full-access:*
+
+# read-only token: GET only on exactly /api/hello
+reader:GET:/api/hello
+
+# update token: POST on exact path, GET on that path and all sub-paths
+updt:POST:/api/v1/ldap/updt
+updt:GET:/api/v1/ldap/updt**
+
+# any method on a path and all sub-paths
+any-method:*:/api/v1/ldap/users**
+
+# match one level deep only (not /api/v1/ldap/users/uid=bob/sub)
+one-level:GET:/api/v1/ldap/users/*
+```
+
+### Glob pattern quick reference
+
+| Pattern          | Matches                                               | Does NOT match                      |
+| ---------------- | ----------------------------------------------------- | ----------------------------------- |
+| `/api/hello`     | `/api/hello`                                          | `/api/hello/sub`                    |
+| `/api/hello**`   | `/api/hello`, `/api/hello/sub`, `/api/hello/sub/deep` | `/api/hell`                         |
+| `/api/hello/**`  | `/api/hello/sub`, `/api/hello/sub/deep`               | `/api/hello`                        |
+| `/api/hello/*`   | `/api/hello/sub`                                      | `/api/hello`, `/api/hello/sub/deep` |
+| `/api/hello.bak` | `/api/hello.bak`                                      | `/api/helloXbak` (`.` is literal)   |
+
+## Behavior
+
+| Situation                                             | Result                                                 |
+| ----------------------------------------------------- | ------------------------------------------------------ |
+| `req.user` is unset (no auth plugin ran)              | Pass through (`next()`) — let upstream auth return 401 |
+| User authenticated but has no rules configured        | 403 Forbidden                                          |
+| User has at least one matching rule                   | 200 / pass through                                     |
+| User has rules but none match the current method+path | 403 Forbidden                                          |
+
+## Full Example
+
+```bash
+DM_AUTH_TOKENS="tok-admin:admin,tok-ro:reader"
+DM_AUTHZ_PER_ROUTES="admin:*,reader:GET:/api/v1/ldap/users**,reader:GET:/api/v1/ldap/groups**"
+
+npx ldap-rest \
+  --plugin core/auth/token \
+  --plugin core/auth/authzPerRoute \
+  --plugin core/ldap/users \
+  --plugin core/ldap/groups \
+  --ldap-url ldap://localhost:389 \
+  ...
+```
+
+```bash
+# admin: any request allowed
+curl -H "Authorization: Bearer tok-admin" http://api/v1/ldap/users
+curl -H "Authorization: Bearer tok-admin" -X DELETE http://api/v1/ldap/users/uid=bob,ou=users,dc=example,dc=org
+
+# reader: GET allowed
+curl -H "Authorization: Bearer tok-ro" http://api/v1/ldap/users   # 200
+
+# reader: write denied
+curl -H "Authorization: Bearer tok-ro" -X POST http://api/v1/ldap/users  # 403
+```
+
+## Difference vs. Other Authz Plugins
+
+| Plugin           | Scope                          | Requires LDAP      |
+| ---------------- | ------------------------------ | ------------------ |
+| `authzPerRoute`  | HTTP method + path             | No                 |
+| `authzPerBranch` | LDAP branch read/write/delete  | No (static config) |
+| `authzDynamic`   | LDAP branch ACL stored in LDAP | Yes                |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -52,6 +52,10 @@
       "types": "./dist/src/plugins/auth/authzPerBranch.d.ts",
       "import": "./dist/plugins/auth/authzPerBranch.js"
     },
+    "./plugin-auth-authzperroute": {
+      "types": "./dist/src/plugins/auth/authzPerRoute.d.ts",
+      "import": "./dist/plugins/auth/authzPerRoute.js"
+    },
     "./plugin-auth-crowdsec": {
       "types": "./dist/src/plugins/auth/crowdsec.d.ts",
       "import": "./dist/plugins/auth/crowdsec.js"
@@ -120,6 +124,10 @@
       "types": "./dist/src/plugins/ldap/organization.d.ts",
       "import": "./dist/plugins/ldap/organization.js"
     },
+    "./plugin-ldap-organizations": {
+      "types": "./dist/src/plugins/ldap/organizations.d.ts",
+      "import": "./dist/plugins/ldap/organizations.js"
+    },
     "./plugin-ldap-passwordpolicy": {
       "types": "./dist/src/plugins/ldap/passwordPolicy.d.ts",
       "import": "./dist/plugins/ldap/passwordPolicy.js"
@@ -188,6 +196,10 @@
       "types": "./dist/src/plugins/twake/calendarResources.d.ts",
       "import": "./dist/plugins/twake/calendarResources.js"
     },
+    "./plugin-twake-cozyprovision": {
+      "types": "./dist/src/plugins/twake/cozyProvision.d.ts",
+      "import": "./dist/plugins/twake/cozyProvision.js"
+    },
     "./plugin-twake-drive": {
       "types": "./dist/src/plugins/twake/drive.d.ts",
       "import": "./dist/plugins/twake/drive.js"
@@ -552,6 +564,7 @@
     "build:dev": "./.dev.mk builddev",
     "build:docker": "./.dev.mk builddocker",
     "build:dockerfile": "./.dev.mk Dockerfile",
+    "build:pages": "tsx scripts/build-pages.ts",
     "build:prod": "npm run clean && NODE_ENV=production rollup -c && npm run build:browser && node scripts/moveBrowserLibs.mjs && npm run build:dockerfile",
     "build:watch": "rollup -c --watch",
     "check": "npm run check:ts && npm run lint && npm run format:check",
@@ -598,6 +611,7 @@
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/chai": "^5.2.2",
     "@types/express": "^5.0.3",
+    "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^10.0.10",
     "@types/multer": "^2.0.0",
     "@types/node": "^24.5.1",
@@ -611,6 +625,7 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^5.5.4",
     "fast-glob": "^3.3.3",
+    "js-yaml": "^4.1.1",
     "mocha": "^11.7.2",
     "nock": "^14.0.10",
     "prettier": "^3.6.2",
@@ -624,6 +639,7 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
+    "@linagora/rabbitmq-client": "^0.1.2",
     "express-openid-connect": "^2.19.2",
     "lemonldap-ng-handler": "^0.7.3",
     "re2": "^1.22.1"