ldap-rest 0.11.0 → 0.11.2

package/docs/usage/plugins/README.md

@@ -62,11 +62,11 @@ Connect to external systems:
 
 ## Utility Plugins
 
-| Plugin                          | Description                   |
-| ------------------------------- | ----------------------------- |
-| [static](utilities/static.md)   | Static file server            |
-| [weblogs](utilities/weblogs.md) | HTTP logging                  |
-| [storage](utilities/storage.md) | Keyed storage with a deadline |
+| Plugin                          | Description                                                         |
+| ------------------------------- | ------------------------------------------------------------------- |
+| [static](utilities/static.md)   | Static file server                                                  |
+| [weblogs](utilities/weblogs.md) | HTTP logging                                                        |
+| [storage](utilities/storage.md) | Keyed storage with a deadline, in LDAP, files, PostgreSQL or Valkey |
 
 ## Plugin Dependencies
 

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

@@ -66,6 +66,36 @@ belongs to nobody's branch, and no administrator could list or change one.
 - A caller named in no `twakeLocalAdminLink` is refused every read (`403`)
   but the top organization's own entry, which `organizations/top` answers.
 
+### Transit: handing an entry over
+
+An administrator can only move an entry between organizations they write, and
+an account created by another tool often carries no `twakeDepartmentLink` at
+all. The transit branch covers both cases: `--authz-transit-branch` names an
+organization through which entries change hands.
+
+```bash
+--authz-transit-branch "ou=Transit,ou=organization,dc=example,dc=com"
+```
+
+An entry is **in transit** when it is attached to that organization, or to
+none (with or without the option).
+
+- Every administrator sees the entries in transit.
+- **Claiming** one (`POST /api/v1/ldap/users/:id/move` towards an
+  organization) asks for write on that organization only.
+- **Putting** one in transit asks for write on the organization it leaves,
+  and nothing on the transit branch: an administrator only lets go of what
+  they manage. Handing an account over to an organization one does not manage
+  is two steps: put it in transit, then its new administrator claims it.
+- Any other change to an entry in transit (attributes, password, status,
+  deletion) is judged as before, so the entry is claimed first.
+
+`GET /api/v1/authz/scope` returns the transit branch as `transit` (`null`
+when there is none), so that a client can offer these moves. A group attached
+to the transit branch follows the same rules through
+`POST /api/v1/ldap/groups/:cn/move`; that endpoint does not move a group
+attached to no organization.
+
 ## Configuration
 
 No configuration file needed - permissions are read from LDAP. Simply load the plugin:
@@ -440,7 +470,10 @@ User exists in `ou=users,dc=example,dc=com` but local admin cannot manage them.
    twakeDepartmentLink: ou=HR,ou=organization,dc=example,dc=com
    ```
 
-2. Or move user to organization branch:
+2. Or let the local admin claim it: an account with no `twakeDepartmentLink`
+   is in transit, see [Transit](#transit-handing-an-entry-over).
+
+3. Or move user to organization branch:
    ```
    From: uid=user,ou=users,dc=example,dc=com
    To:   uid=user,ou=users,ou=HR,ou=organization,dc=example,dc=com

package/docs/usage/plugins/ldap/flat-generic.md

@@ -383,6 +383,32 @@ Content-Type: application/json
 }
 ```
 
+#### Entries created by other tools
+
+An entry written by another tool may lack an object class the schema
+declares, and the directory then refuses an attribute that class carries: a
+bare `inetOrgPerson` in the users branch cannot take `twakeDepartmentLink`,
+which `twakeWhitePages` brings. When a modify through LDAP-Rest (this route,
+`/move`, a state change…) writes such an attribute, the **auxiliary** class
+declared for the branch that allows it is added in the same write, provided
+the entry holds, or receives, that class's mandatory attributes. Only what
+the write needs is added, and a write the directory would accept is never
+changed: several entities may share a branch (`users`, `posixAccounts` and
+`sshPublicKeys` all live in `ou=users`) without every entry being given all
+their classes.
+
+A missing **structural** class, such as `twakeAccount`, cannot be added to an
+existing entry: the write answers `409`, and the reason is logged once per
+entry. The same applies to groups under `--ldap-group-base` (when it is set)
+with `--group-class`, and to the organization tree with
+`--ldap-organization-class`. Nothing is added when the change names
+`objectClass` itself.
+
+The repair reads the directory schema, kept for
+`--ldap-raw-schema-cache-ttl`, and the entry's classes when a written
+attribute belongs to a declared auxiliary class. `DM_LDAP_FLAT_AUTO_REPAIR=false`
+turns it off.
+
 ### Delete Entry
 
 ```bash

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

@@ -197,7 +197,7 @@ Combine with an authentication plugin ([token](../auth/token.md), [oidc](../auth
 
 ## 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.
+- **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, and so does the [object class repair](flat-generic.md#entries-created-by-other-tools), which loads it even without this plugin.
 - **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.
 

package/docs/usage/plugins/utilities/storage.md

@@ -26,13 +26,17 @@ which is invisible in a configuration.
   --storage-ldap-base ou=Records,dc=example,dc=com
 ```
 
-| Option                        | Environment                    | Default              | Description                                               |
-| ----------------------------- | ------------------------------ | -------------------- | --------------------------------------------------------- |
-| `--storage-backend`           | `DM_STORAGE_BACKEND`           | _(none)_             | `ldap` or `file`. Empty means the plugin refuses to start |
-| `--storage-sweep-interval`    | `DM_STORAGE_SWEEP_INTERVAL`    | `600`                | Seconds between two passes dropping expired records       |
-| `--storage-ldap-base`         | `DM_STORAGE_LDAP_BASE`         | _(none)_             | Branch the `ldap` backend writes to                       |
-| `--storage-ldap-object-class` | `DM_STORAGE_LDAP_OBJECT_CLASS` | `applicationProcess` | Object class of the entries it writes                     |
-| `--storage-file-directory`    | `DM_STORAGE_FILE_DIRECTORY`    | _(none)_             | Directory the `file` backend writes to                    |
+| Option                        | Environment                    | Default              | Description                                                                     |
+| ----------------------------- | ------------------------------ | -------------------- | ------------------------------------------------------------------------------- |
+| `--storage-backend`           | `DM_STORAGE_BACKEND`           | _(none)_             | `ldap`, `file`, `postgres` or `valkey`. Empty means the plugin refuses to start |
+| `--storage-sweep-interval`    | `DM_STORAGE_SWEEP_INTERVAL`    | `600`                | Seconds between two passes dropping expired records                             |
+| `--storage-ldap-base`         | `DM_STORAGE_LDAP_BASE`         | _(none)_             | Branch the `ldap` backend writes to                                             |
+| `--storage-ldap-object-class` | `DM_STORAGE_LDAP_OBJECT_CLASS` | `applicationProcess` | Object class of the entries it writes                                           |
+| `--storage-file-directory`    | `DM_STORAGE_FILE_DIRECTORY`    | _(none)_             | Directory the `file` backend writes to                                          |
+| `--storage-postgres-url`      | `DM_STORAGE_POSTGRES_URL`      | _(none)_             | Connection string of the `postgres` backend                                     |
+| `--storage-postgres-table`    | `DM_STORAGE_POSTGRES_TABLE`    | `ldap_rest_storage`  | Table it writes to, `schema.table` accepted                                     |
+| `--storage-valkey-url`        | `DM_STORAGE_VALKEY_URL`        | _(none)_             | URL of the `valkey` backend (`redis://…` or `rediss://…`)                       |
+| `--storage-valkey-prefix`     | `DM_STORAGE_VALKEY_PREFIX`     | `ldap-rest:`         | Prefix of the keys it writes                                                    |
 
 `core/storage` is in the priority list, so it is registered before the
 plugins that consume it whatever order they are written in. A consumer that
@@ -61,18 +65,65 @@ The directory is the plugin's own: nothing else should be writing there, and
 the sweeper removes what it finds expired. It is local to one process, so it
 suits a single instance, not a cluster sharing one verdict.
 
+### `postgres`
+
+One row per record in `--storage-postgres-table`, with the consumer's
+namespace and key kept verbatim beside the value and an `expires_at` column,
+so a `SELECT` tells what a record is about. Needs the optional `pg` package.
+
+The table is created at the first connection when it is not there. A role
+that may not create tables works once it exists:
+
+```sql
+CREATE TABLE ldap_rest_storage (
+  namespace text NOT NULL,
+  key text NOT NULL,
+  value text NOT NULL,
+  expires_at timestamptz NOT NULL,
+  PRIMARY KEY (namespace, key)
+);
+CREATE INDEX ldap_rest_storage_expires_at ON ldap_rest_storage (expires_at);
+GRANT SELECT, INSERT, UPDATE, DELETE ON ldap_rest_storage TO ldap_rest;
+```
+
+Several instances can share the table and sweep it at once. PostgreSQL
+refuses a NUL in `text`, so a key holding one cannot be kept: the write
+fails.
+
+### `valkey`
+
+One key per record, `--storage-valkey-prefix` followed by the namespace and
+the key, expiring with the record: nothing is left to sweep. Works with Redis
+too. Needs the optional `iovalkey` package.
+
+**The instance must not evict.** An instance configured as a cache
+(`allkeys-lru`, `volatile-lru` and the like) drops keys under memory pressure,
+and every key this backend writes has a TTL: a Back-Channel Logout mark
+evicted early reopens the session it closed. Use an instance with
+`maxmemory-policy noeviction`, which answers a full memory with a failed
+write — reported to the identity provider — rather than a silent loss.
+
+A connection lost while running is retried in the background; meanwhile, reads
+answer "absent" with a warning and writes fail at once instead of waiting.
+
+`postgres` and `valkey` connect at startup, and report there an address that
+does not answer or a package that is not installed; the server starts anyway,
+and every operation tries to connect again.
+
 ## Expiry
 
 Two rules the backends do not get to reinterpret:
 
 - **Expiry is enforced on read.** A record past its deadline is answered as
   absent whatever the sweeper has done, so a sweeper running late is a
-  storage cost, never a wrong answer.
+  storage cost, never a wrong answer. Expiry is judged by this server's clock,
+  the sweep and the Valkey TTL included, so a database clock running ahead
+  cannot drop a record early.
 - **The deadline belongs to the consumer.** How long a record lives is the
   policy of whoever wrote it. The store is told an instant and respects it.
 
-Keys are namespaced per consumer, so two of them cannot collide in one branch
-or one directory.
+Keys are namespaced per consumer, so two of them cannot collide in one branch,
+directory, table or instance.
 
 ## For Plugin Authors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -232,6 +232,14 @@
       "types": "./dist/src/plugins/storage/ldap.d.ts",
       "import": "./dist/plugins/storage/ldap.js"
     },
+    "./plugin-storage-postgres": {
+      "types": "./dist/src/plugins/storage/postgres.d.ts",
+      "import": "./dist/plugins/storage/postgres.js"
+    },
+    "./plugin-storage-valkey": {
+      "types": "./dist/src/plugins/storage/valkey.d.ts",
+      "import": "./dist/plugins/storage/valkey.js"
+    },
     "./plugin-twake-appaccountsapi": {
       "types": "./dist/src/plugins/twake/appAccountsApi.d.ts",
       "import": "./dist/plugins/twake/appAccountsApi.js"
@@ -727,6 +735,7 @@
     "@types/mocha": "^10.0.10",
     "@types/multer": "^2.0.0",
     "@types/node": "^24.5.1",
+    "@types/pg": "^8.23.1",
     "@types/supertest": "^6.0.3",
     "@typescript-eslint/eslint-plugin": "^8.44.0",
     "@typescript-eslint/parser": "^8.44.0",
@@ -755,7 +764,9 @@
   "optionalDependencies": {
     "@linagora/rabbitmq-client": "^0.1.2",
     "express-openid-connect": "^2.19.2",
+    "iovalkey": "^0.4.0",
     "lemonldap-ng-handler": "^0.7.3",
+    "pg": "^8.23.0",
     "re2": "^1.22.1"
   },
   "engines": {