ldap-rest 0.11.2 → 0.13.0

package/dist/src/plugins/ldap/groups.d.ts

@@ -86,6 +86,11 @@ export default class LdapGroups extends DmPlugin {
     cn: string;
     schema?: Schema;
     constructor(server: DM);
+    /**
+     * The loaded group schema, before it is used: a subclass declares there
+     * the attributes it writes.
+     */
+    protected adaptSchema(schema: Schema): Schema;
     /**
      * Remove deleted entries from groups once the delete has landed: a delete
      * refused, failed or turned into something else by another plugin leaves

package/dist/src/plugins/scim/filter.d.ts

@@ -1,7 +1,8 @@
 import type { ResourceMapping } from './types';
 export interface FilterOptions {
-    /** LDAP attribute whose presence marks a User as locked. */
+    /** LDAP attribute and value that mark a User as locked. */
     lockAttribute?: string;
+    lockValue?: string;
     /**
      * Whether this resource type carries SCIM `active`. Users do; Groups do
      * not, and must get `invalidFilter` rather than a filter built out of a

package/dist/src/plugins/scim/groups.d.ts

@@ -36,6 +36,7 @@ export declare class ScimGroups {
     private readonly users;
     private readonly hooks;
     private readonly mapping;
+    private readonly attributes;
     private readonly rdnAttribute;
     private readonly objectClass;
     private readonly idAttribute;

package/dist/src/plugins/scim/mapping.d.ts

@@ -47,9 +47,9 @@ export interface MappingContext {
     baseUrl?: string;
     scimPrefix: string;
     /**
-     * LDAP attribute whose *presence* marks the account as locked, and the
-     * value written to lock it. Both come from `resolveLockConfig()`, which is
-     * the only place the defaults live: re-defaulting here would let a context
+     * LDAP attribute, and the value in it that marks the account as locked and
+     * is written to lock it. Both come from `resolveLockConfig()`, which is the
+     * only place the defaults live: re-defaulting here would let a context
      * built outside the plugin reach the directory with a pair the startup
      * guard never saw. Groups have no `active`, so they pass empty strings.
      */
@@ -58,8 +58,8 @@ export interface MappingContext {
 }
 /**
  * SCIM `active` (RFC 7643 section 4.1.1) has no direct LDAP equivalent. We
- * model it on the presence of one attribute: present means locked, absent
- * means active.
+ * model it on one attribute holding one value: that value means locked,
+ * anything else, absence included, means active.
  *
  * The default is the ppolicy overlay's `pwdAccountLockedTime`, whose
  * conventional "locked forever" value is a GeneralizedTime in the distant
@@ -104,7 +104,10 @@ export declare function setLockConfigWarn(sink: (message: string) => void): (mes
  * told apart from a deliberate local schema, so they are warned about: what
  * the directory does with a value is beyond anything this can check.
  */
-export declare function resolveLockConfig(attribute: string, value: string): {
+export declare function resolveLockConfig(attribute: string, value: string, options?: {
+    attribute: string;
+    value: string;
+}): {
     attribute: string;
     value: string;
 };
@@ -119,8 +122,19 @@ export declare function resolveLockConfig(attribute: string, value: string): {
  * translator cannot drift apart.
  */
 export declare function readActive(value: unknown): boolean | undefined;
-/** Is this entry locked, per the configured lock attribute? */
-export declare function isLocked(entry: AttributesList, ctx: MappingContext): boolean;
+/**
+ * Is this entry locked, per the configured lock pair? Only the lock value
+ * counts: a ppolicy lockout after failed binds is a timestamp in the same
+ * attribute, and it does not deactivate the account.
+ */
+export declare function isLocked(entry: AttributesList, ctx: Pick<MappingContext, 'lockAttribute' | 'lockValue'>): boolean;
+/**
+ * Does the entry hold this value in this attribute? Both compared
+ * case-insensitively, whatever the attribute's matching rule, and an
+ * attribute given as an empty array is absent. SCIM `active` and the twake
+ * lifecycle plugins read the same lock pair through it.
+ */
+export declare function holdsValue(entry: AttributesList, attribute: string, value: string): boolean;
 /** Resolve the SCIM id for an LDAP entry, per configuration. */
 export declare function resolveScimId(entry: AttributesList, ctx: MappingContext): string | undefined;
 export declare function buildLocation(id: string, ctx: MappingContext): string | undefined;

package/dist/src/plugins/scim/patch.d.ts

@@ -28,8 +28,8 @@ export interface PatchContext {
     /** The LDAP attribute holding members, default 'member'. */
     memberAttribute?: string;
     /**
-     * For Users: the attribute whose presence marks the account as locked, and
-     * the value to write when SCIM `active` is set to false.
+     * For Users: the attribute and value that mark the account as locked;
+     * SCIM `active: false` writes that value.
      */
     lockAttribute?: string;
     lockValue?: string;
@@ -44,6 +44,13 @@ export interface PatchContext {
     current: AttributesList;
 }
 export declare function patchToModifyRequest(patch: PatchRequest, ctx: PatchContext): Promise<ModifyRequest>;
+/**
+ * Write a PATCH, read and computed anew by `attempt` each time. A delete
+ * only names values the read showed, so noSuchAttribute means a concurrent
+ * write removed one of them: the PATCH is played once more on a fresh read,
+ * then refused with 409.
+ */
+export declare function writePatch(dn: string, attempt: () => Promise<void>): Promise<void>;
 /**
  * Apply PATCH to a SCIM resource object in-memory (used for PUT-equivalent
  * or when the resource handler prefers object-level manipulation before

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

@@ -0,0 +1,89 @@
+import type { Express } from 'express';
+import type { DM } from '../../bin';
+import type { Schema } from '../../config/schema';
+import type { Hooks } from '../../hooks';
+import type { AttributeValue } from '../../lib/ldapActions';
+import LdapGroups from '../ldap/groups';
+import { type LifecycleAttributes } from './lifecycleAttributes';
+/** The values of an attribute, whatever shape the directory gave them. */
+export declare function values(value: AttributeValue | undefined): string[];
+export default class TwakeGroups extends LdapGroups {
+    name: string;
+    protected readonly groupBase: string;
+    protected readonly userBase: string;
+    protected readonly groupPattern: RegExp;
+    protected readonly attrs: LifecycleAttributes;
+    private readonly orgPattern;
+    private readonly displayName;
+    private readonly color;
+    private readonly createdAt;
+    private readonly maxPage;
+    private readonly memberFields;
+    constructor(server: DM);
+    /**
+     * Declare the group attributes under their configured names, whatever case
+     * the schema spells them in, or add them when it does not: the schema does
+     * not have to follow a renamed attribute.
+     */
+    protected adaptSchema(schema: Schema): Schema;
+    /**
+     * No `ldapdeletedone`: an erased member leaves its groups through the
+     * directory's referential integrity, whatever made the delete. The cleanup
+     * inherited from core/ldap/groups writes through LDAP-Rest, so every group
+     * would announce a member removed on an erase, which publishes nothing.
+     */
+    hooks: Hooks;
+    /**
+     * The id a `scimgroupcreate` hook assigns names the entry only when the
+     * SCIM group mapping leaves the RDN attribute alone.
+     */
+    afterLoad(): void;
+    /** The organization a group DN belongs to, if it is a group at all. */
+    organizationOf(dn: string): string | undefined;
+    groupBaseOf(org: string): string;
+    userBaseOf(org: string): string;
+    /**
+     * A group's members belong to its organization, as a provider is trusted
+     * within its own organization only. The placeholder belongs to none.
+     */
+    private checkMembers;
+    /**
+     * A tombstone keeps its memberships until it is erased, and is hidden from
+     * them, so every API reads the same member list.
+     */
+    private hideTombstones;
+    private tombstonesOf;
+    /**
+     * Only the organization routes: the flat `/v1/ldap/groups` of
+     * core/ldap/groups would read one base that holds no group here.
+     */
+    api(app: Express): void;
+    private groupDn;
+    private get userAttribute();
+    /** Every route answers 404 for a missing organization, 410 for a deleted one. */
+    private checkOrganization;
+    /** Page, search and sort of a list route, or a refusal of them. */
+    private page;
+    private sorted;
+    /** A group as the routes answer it: members named by their RDN value. */
+    private groupOf;
+    private groups;
+    private readGroup;
+    /** The group of that display name in the organization, if any. */
+    private named;
+    /** A write to a group that is not there answers 404. */
+    private onGroup;
+    private listRoute;
+    private createRoute;
+    private updateRoute;
+    private membersRoute;
+    /**
+     * Users of the organization by name, read in pages of the size limit. A
+     * tombstone is no user: it cannot be added, as it would join hidden.
+     */
+    private users;
+    private profiles;
+    private addMembersRoute;
+    private dropPlaceholder;
+    private removeMemberRoute;
+}

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

@@ -0,0 +1,102 @@
+/**
+ * @module plugins/twake/instances
+ *
+ * Gives every account this server creates its workplace instance, once its
+ * entry is written, from the Cloudery or from the cozy-stack admin API. The
+ * address is written once the instance exists, then `user.created` is
+ * published and the entry marked. The event is sent at least once.
+ *
+ * See `docs/usage/plugins/integrations/instances.md`.
+ */
+import type { Express, Request } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
+import { type InstanceProvider, type InstanceRequest } from '../../lib/instanceProviders';
+import type { AttributesList } from '../../lib/ldapActions';
+export interface WorkplaceCreated {
+    twakeId?: string;
+    internalEmail?: string;
+    workplaceFqdn?: string;
+}
+/** An account's instance request, and the id `user.created` names it by. */
+interface Account extends InstanceRequest {
+    twakeId: string;
+}
+export default class TwakeInstances extends DmPlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        rabbitmq: string;
+    };
+    protected readonly patterns: RegExp[];
+    protected readonly provider: InstanceProvider;
+    protected readonly fqdnAttribute: string;
+    protected readonly sentAttribute: string;
+    private readonly locale;
+    private readonly lifecycle;
+    /** Work on one account, or organization, waits for the work before it */
+    private readonly queues;
+    constructor(server: DM);
+    hooks: Hooks;
+    /**
+     * Without a broker `user.created` could not be sent, and with the Cloudery
+     * no address would ever arrive: the server does not start.
+     */
+    api(app: Express): Promise<void>;
+    /**
+     * Make sure this account has its instance: covers a refused or lost
+     * creation, and a `workplace.created` that never arrived. With a request,
+     * the account is read and written with the caller's rights.
+     */
+    ensureInstance(dn: string, req?: Request): Promise<'ready' | 'pending'>;
+    /**
+     * Ask for an organization's own instance, which the Cloudery also needs as
+     * an organization. `organization.created` follows once it exists. For the
+     * application that creates organizations to call.
+     */
+    ensureOrganization(org: {
+        id: string;
+        name: string;
+        domain: string;
+    }): Promise<'ready' | 'pending'>;
+    private organizationRequest;
+    /**
+     * The Cloudery builds no member instance for an organization it does not
+     * have, so a member asks for a missing one first. The organization is
+     * marked when its own workplace.created arrives. Not serialized on the
+     * organization: its work releases members, which would wait on this one.
+     */
+    private requestOrganization;
+    onWorkplaceCreated(message: WorkplaceCreated): Promise<void>;
+    private settle;
+    /** Find the instance, or ask for it; write it down once it exists. */
+    private provide;
+    protected ready(dn: string, entry: AttributesList, account: Account, fqdn: string, req?: Request): Promise<void>;
+    private organizationReady;
+    /** Send the user.created held while the organization at `dn` was pending */
+    private releaseMembers;
+    /** Announce a held member, with the address rule ensureInstance applies */
+    private release;
+    /**
+     * Run `work` once the work already queued for `key` is over. One replica
+     * only: across replicas, `user.created` may still be sent twice.
+     */
+    private serialized;
+    private get organizationId();
+    private get organizationDomain();
+    private get organizationName();
+    private get organizationFqdn();
+    private organizationMail;
+    private isOrganization;
+    private findOrganization;
+    private read;
+    protected announce(exchange: string, key: string, message: Record<string, unknown>): Promise<void>;
+    /** What to ask for this account, when it gets an instance at all. */
+    protected account(dn: string, entry: AttributesList): Account | undefined;
+    private match;
+    private id;
+    protected value(entry: AttributesList, attribute: string): unknown;
+    protected findByMail(email: string, req?: Request): Promise<AttributesList | undefined>;
+}
+export {};

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

@@ -0,0 +1,29 @@
+/**
+ * @module plugins/twake/lifecycleAttributes
+ *
+ * The attributes that carry an account's lifecycle (its role, its lock, its
+ * deletion), read from the `--twake-lifecycle-*` options: the ones
+ * `core/twake/lifecycleEvents` reads, and `core/twake/tombstone` writes.
+ */
+import type { Config } from '../../bin';
+import type { AttributesList, AttributeValue } from '../../lib/ldapActions';
+export type DeletedAtFormat = 'iso8601' | 'generalizedTime';
+export interface LifecycleAttributes {
+    role: string;
+    lock: string;
+    lockValue: string;
+    deleted: string;
+    deletedValue: string;
+    deletedAt: string;
+    deletedAtFormat: DeletedAtFormat;
+    reason: string;
+}
+export declare function lifecycleAttributes(config: Config): LifecycleAttributes;
+/** An attribute of an entry, whatever case the caller spelled its name in. */
+export declare function valueOf<T>(entry: Record<string, T>, attribute: string): T | undefined;
+export declare function first(value: AttributeValue | null | undefined): string | undefined;
+export declare const isTombstone: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
+export declare const isLocked: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
+export declare function formatDeletedAt(date: Date, format: DeletedAtFormat): string;
+/** A deletion date as the directory holds it, or undefined if unreadable. */
+export declare function parseDeletedAt(value: string, format: DeletedAtFormat): Date | undefined;

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

@@ -0,0 +1,62 @@
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
+export declare const LIFECYCLE_EVENTS: readonly ["created", "roleChanged", "disabled", "enabled", "updated", "memberAdded", "memberRemoved", "deleted"];
+export type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number];
+declare const MEMBER_LISTS: readonly ["$members", "$added", "$removed"];
+/** A payload field listing members, each read and shaped by `fields`. */
+interface MemberList {
+    list: (typeof MEMBER_LISTS)[number];
+    fields: Record<string, string>;
+}
+type Payload = Record<string, string | MemberList>;
+type Condition = Record<string, string>;
+interface Target {
+    exchange: string;
+    routingKey: string;
+    payload: Payload;
+    when: Condition;
+}
+interface Rule {
+    dn: RegExp;
+    targets: Partial<Record<LifecycleEvent, Target[]>>;
+}
+export declare function parseRules(source: string): Rule[];
+export default class TwakeLifecycleEvents extends DmPlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        onLdapChange: string;
+        rabbitmq: string;
+    };
+    private readonly rules;
+    private readonly attrs;
+    private readonly memberAttribute;
+    constructor(server: DM);
+    /**
+     * core/rabbitmq connects lazily and hands back no client when it cannot:
+     * every event would then be lost, so the server does not start.
+     */
+    assertComposition(): Promise<void>;
+    /**
+     * SCIM deactivates by writing its own lock: on another attribute or
+     * value, `disabled` and `enabled` never follow a SCIM `active` change.
+     */
+    afterLoad(): void;
+    hooks: Hooks;
+    private replay;
+    private match;
+    private onEntryChange;
+    /** The members of an entry, the group placeholder left out. */
+    private members;
+    private memberDiff;
+    /**
+     * A member list of a payload: one read per member, a tombstone left out,
+     * and a member no longer in the directory given its RDN alone.
+     */
+    private memberPayloads;
+    private readMember;
+    private resolve;
+    private publish;
+}
+export {};

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

@@ -0,0 +1,86 @@
+/**
+ * @module plugins/twake/tombstone
+ *
+ * Turns the delete of an account into a tombstone: the entry stays, flagged
+ * as deleted, dated, locked, with the reason and without the attributes the
+ * deployment wants gone. The address it holds cannot be taken again until the
+ * tombstone is erased.
+ *
+ * SCIM treats a tombstone as gone. Erasing removes the entry and its group
+ * memberships, once the deletion is old enough or when forced, and announces
+ * nothing: the deletion already did.
+ *
+ * See `docs/usage/plugins/integrations/tombstone.md`.
+ */
+import type { Express, Request } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
+export default class TwakeTombstone extends DmPlugin {
+    name: string;
+    roles: Role[];
+    private readonly attrs;
+    private readonly patterns;
+    private readonly defaultReason;
+    private readonly reasonHeader;
+    private readonly reasons;
+    private readonly clearAttributes;
+    private readonly eraseMinAge;
+    private readonly groupBases;
+    private readonly scimPrefix;
+    /** Deletes asked for through {@link tombstone}, with their reason. */
+    private readonly reasonFor;
+    /** Entries being erased: their delete must reach the directory. */
+    private readonly erasing;
+    constructor(server: DM);
+    /**
+     * Last in the delete and add chains: a plugin that may refuse the request
+     * judges it before a tombstone is written or erased.
+     */
+    afterLoad(): void;
+    hooks: Hooks;
+    api(app: Express): void;
+    /**
+     * Delete an entry as a tombstone recording this reason. Goes through the
+     * directory's delete, so every plugin judging deletes judges this one.
+     */
+    tombstone(dn: string, reason: string, req?: Request): Promise<void>;
+    /**
+     * Remove a tombstone and its group memberships. Refused while the deletion
+     * is younger than the configured age, unless forced.
+     */
+    erase(dn: string, { force, req }?: {
+        force?: boolean;
+        req?: Request;
+    }): Promise<void>;
+    /**
+     * core/ldap/trash moves a deleted entry away before this plugin, last in
+     * the delete chain, sees it: no tombstone would be written, and an erase
+     * would move the tombstone instead of removing it.
+     */
+    assertComposition(): void;
+    /**
+     * Erase a tombstone so a SCIM create can take its identity. The directory
+     * may still refuse the add; the tombstone and its memberships are then put
+     * back once the response is sent.
+     */
+    private replace;
+    /**
+     * Put back a tombstone the add did not replace, with its memberships. A
+     * group the erase left holding only the placeholder loses it again.
+     */
+    private restore;
+    private matches;
+    private isScim;
+    private checkReason;
+    private reasonOf;
+    private read;
+    private writeTombstone;
+    private groupsOf;
+    private leaveGroups;
+    /**
+     * core/ldap/groups and refint clean the same memberships once the delete
+     * lands, so each outcome of a race with them counts as done.
+     */
+    private leaveGroup;
+}

package/docs/client-development/api/rest-api.md

@@ -244,6 +244,8 @@ curl -H "Accept: application/json" \
 - `features.ldapFlatGeneric.flatResources`: Array of flat LDAP resources (users, positions, etc.)
 - `features.ldapGroups`: Group management configuration (if enabled)
 - `features.ldapOrganizations`: Organization tree configuration (if enabled)
+- `features.openidconnect.endpoints.logout`: the logout route, when OpenID Connect
+  guards the server ([details](../../usage/plugins/auth/oidc.md#logout))
 
 ---
 
@@ -536,6 +538,12 @@ Retrieve all users or filter by attributes.
 - `match` - Filter value (partial match with wildcards)
 - `attribute` - Attribute name to filter on
 - `attributes` - Comma-separated list of attributes to return
+- `limit` - Return at most this many users; `X-Result-Truncated: true` then
+  says others were left out. Without it, a list longer than the directory's
+  size limit is answered `422`
+  ([details](../../usage/plugins/ldap/flat-generic.md#long-lists)). Only the
+  flat entities' lists (users and the other schema-driven entities) take
+  `limit` for now; the [groups list](#list-groups) does not.
 
 **Example Request (all users):**
 
@@ -762,6 +770,11 @@ Retrieve all groups or filter by name.
 - `match` - Filter groups by CN (supports LDAP filter format or simple string)
 - `attributes` - Comma-separated list of attributes to return
 
+This list does not take `limit` yet: `?limit=` is ignored, no
+`X-Result-Truncated` header is sent, and a list longer than the directory's
+size limit fails with `500` rather than the `422` of the
+[users list](#list-users).
+
 **Example Request (all groups):**
 
 ```bash
@@ -1044,6 +1057,7 @@ curl -X DELETE \
 | 403         | Forbidden - Insufficient permissions   |
 | 404         | Not Found - Resource doesn't exist     |
 | 409         | Conflict - Resource already exists     |
+| 422         | Unprocessable - see below              |
 | 500         | Internal Server Error                  |
 
 ### Error Response Format
@@ -1138,6 +1152,18 @@ All errors return a JSON object with an error message:
 }
 ```
 
+#### 422 Unprocessable Entity
+
+**List longer than the directory's size limit** (flat entities' lists, when
+no `limit` was given —
+[details](../../usage/plugins/ldap/flat-generic.md#long-lists)):
+
+```json
+{
+  "error": "Too many entries to list at once: the directory's size limit was exceeded. Narrow the search, or pass `limit`."
+}
+```
+
 #### 500 Internal Server Error
 
 **LDAP Connection Error:**
@@ -1200,9 +1226,15 @@ Use the correct operation type:
 - **add**: Add values to multi-valued attributes (error if already exists)
 - **delete**: Remove attributes or specific values
 
-### Pagination
+### Long Lists
 
-For large result sets, consider implementing client-side pagination or use LDAP paging (controlled server-side).
+The API has no pagination. A flat entity's list (users and the other
+schema-driven entities) takes `limit` to bound its answer, and says with
+`X-Result-Truncated: true` that entries were left out: narrow the search with
+`match` and `attribute` to reach them. Without `limit`, a list longer than the
+directory's size limit is answered `422`. See
+[long lists](../../usage/plugins/ldap/flat-generic.md#long-lists); the groups
+list does not take `limit` yet.
 
 ### Schema Validation
 

package/docs/plugin-development/hooks.md

@@ -13,10 +13,34 @@ Typescript definitions into [hooks.ts](./src/hooks.ts)
 - **ldapopts**: called before any ldapsearch to modify search options
 - **ldapsearchresult**: called after any ldapsearch to modify search result
 - **ldapaddrequest**: called before any ldapadd
+- **ldapadddone**: launched once an ldapadd has written the entry, not awaited
+- **ldapaddafter**: awaited once an ldapadd has written the entry, before it
+  answers, see [below](#ldapaddafter)
 - **ldapmodifyrequest**: called before any ldapmodify
 - **ldapdeleterequest**: called before any ldapdelete
 - **ldaprenamerequest**: called before any ldap rename/modifyDN operation
 
+### ldapaddafter
+
+For what must follow an add within the same request, such as provisioning
+the account the entry describes.
+
+- Subscribers get `[dn, entry]` and the change context, as `ldapadddone`
+  does. They run one after the other, and `add()` answers once the last has
+  returned.
+- An error is logged and goes no further: the add has succeeded, and the
+  next subscriber still runs. A subscriber that can fail owns its repair
+  path, and should be safe to run again on the same entry.
+- It fires for every add, including those made without a request (trash,
+  storage, appAccountsConsistency, externalUsersInGroups), whose context is
+  empty. Some of these follow an API call all the same, so select entries by
+  their DN or attributes rather than by an empty context.
+- The entry is the one submitted, after `ldapaddrequest`, not what the
+  directory holds: no operational attributes, and the password as given.
+- `ldapadddone` and `onLdapEntryChange` fire whatever this hook does, and in
+  no set order with it: an add event may or may not include what a
+  subscriber here wrote.
+
 ## [onChange](../usage/plugins/ldap/on-change.md) hooks
 
 - **onLdapEntryChange**: called after any write, with the entry before and