ldap-rest 1.2.1 → 2.0.0

package/dist/src/hooks.d.ts

@@ -4,9 +4,10 @@
  */
 import type { Entry, SearchOptions, SearchResult } from 'ldapts';
 import type { Request, Response } from 'express';
-import type { ModifyRequest, AttributesList, AttributeValue } from './lib/ldapActions';
+import type { ModifyRequest, AttributesList, AttributeValue, LdapList } from './lib/ldapActions';
 import type { ChangesToNotify } from './plugins/ldap/onChange';
 import type { ChangeContext } from './lib/changeContext';
+import type { BulkResponse, ScimGroup, ScimUser } from './plugins/scim/types';
 import * as utils from './lib/utils';
 export type MaybePromise<T> = Promise<T> | T;
 export type ChainedHook<T> = (arg: T) => MaybePromise<T>;
@@ -29,7 +30,6 @@ export interface OidcSessionClaims {
 }
 export type OidcLogoutToken = OidcSessionClaims;
 export type VoidHook<T extends unknown[]> = (...args: T) => MaybePromise<void>;
-export type OtherHook = Function;
 export { utils };
 /**
  * All available hooks
@@ -56,11 +56,11 @@ export interface Hooks {
      */
     ldapsearchfilter?: ChainedHook<[SearchResult, Request?, SearchOptions?]>;
     ldapaddrequest?: ChainedHook<[string, AttributesList, Request?]>;
-    ldapadddone?: (args: [string, AttributesList], context?: ChangeContext) => MaybePromise<void>;
+    ldapadddone?: (dn: string, entry: AttributesList, context?: ChangeContext) => MaybePromise<void>;
     /** See docs/plugin-development/hooks.md#ldapaddafter */
-    ldapaddafter?: (args: [string, AttributesList], context?: ChangeContext) => MaybePromise<void>;
+    ldapaddafter?: (dn: string, entry: AttributesList, context?: ChangeContext) => MaybePromise<void>;
     ldapmodifyrequest?: ChainedHook<[string, ModifyRequest, number, Request?]>;
-    ldapmodifydone?: (args: [string, ModifyRequest, number], context?: ChangeContext) => MaybePromise<void>;
+    ldapmodifydone?: (dn: string, changes: ModifyRequest, op: number, context?: ChangeContext) => MaybePromise<void>;
     /**
      * Once a modify is over, whatever became of it, after its `ldapmodifydone`
      * subscribers have returned; with the operation number
@@ -75,7 +75,7 @@ export interface Hooks {
      */
     ldapdeleteend?: (op: number) => MaybePromise<void>;
     ldaprenamerequest?: ChainedHook<[string, string, Request?]>;
-    ldaprenamedone?: (args: [string, string], context?: ChangeContext) => MaybePromise<void>;
+    ldaprenamedone?: (dn: string, newDn: string, context?: ChangeContext) => MaybePromise<void>;
     /**
      * Once a rename is over, whatever became of it, after its `ldaprenamedone`
      * subscribers have returned; with the operation number its request and
@@ -122,14 +122,20 @@ export interface Hooks {
     /** LdapGroups plugin */
     ldapgroupvalidatemembers?: ChainedHook<[string, string[]]>;
     ldapgroupadd?: ChainedHook<[string, AttributesList]>;
-    ldapgroupadddone?: (args: [string, AttributesList]) => MaybePromise<void>;
+    ldapgroupadddone?: (dn: string, entry: AttributesList) => MaybePromise<void>;
     ldapgroupmodify?: ChainedHook<[string, ModifyRequest, number]>;
-    ldapgroupmodifydone?: (args: [string, ModifyRequest, number]) => MaybePromise<void>;
+    ldapgroupmodifydone?: (dn: string, changes: ModifyRequest, op: number) => MaybePromise<void>;
+    ldapgrouprename?: ChainedHook<[string, string]>;
+    ldapgrouprenamedone?: (dn: string, newDn: string) => MaybePromise<void>;
+    /** Before `ldapgroupadd`, to judge the group about to be created */
+    ldapgroupvalidatenew?: ChainedHook<[string, AttributesList]>;
+    /** Before `ldapgroupmodify`, to judge the changes about to be written */
+    ldapgroupvalidatechanges?: ChainedHook<[string, ModifyRequest]>;
     ldapgroupdelete?: ChainedHook<string>;
     ldapgroupdeletedone?: (dn: string) => MaybePromise<void>;
     ldapgroupaddmember?: ChainedHook<[string, string[]]>;
-    ldapgroupdeletemember?: ChainedHook<[string, string[]]>;
-    _ldapgrouplist?: ChainedHook<AsyncGenerator<SearchResult>>;
+    ldapgroupdeletemember?: ChainedHook<[string, string]>;
+    _ldapgrouplist?: ChainedHook<LdapList>;
     /**
      * "onLdapChange"
      *
@@ -150,22 +156,54 @@ export interface Hooks {
     onLdapDriveQuotaChange?: (dn: string, oldDriveQuota: number | null, newDriveQuota: number | null) => MaybePromise<void>;
     /** externalUsersInGroup */
     externaluserentry?: ChainedHook<[string, AttributesList]>;
-    externaluseradded?: (dn: string, mail: string) => MaybePromise<void>;
+    /** The external member was created, with its DN and the entry written */
+    externaluseradded?: (dn: string, entry: AttributesList) => MaybePromise<void>;
     /**
-     * Generic flat resource move hooks
-     * Pattern: {hookPrefix}move
-     * Examples: ldapusermove, ldappositionmove, etc.
-     *
-     * move: before moving - can modify target or cancel
-     * Note: After move, onLdapChange is triggered automatically by modifyEntry()
+     * Generic flat resource hooks, one set per `--ldap-flat-schema` entity,
+     * `ldapusermove` for one renamed user: `{hookPrefix}` followed by the
+     * suffix of the shared hook of the same kind, see {@link FlatHookPrefix}.
+     * An entity's `move` hook takes `[dn, targetOrgDn, request?]`, and a move
+     * is followed by `onLdapChange`, as a modify is.
      */
-    [K: string]: ChainedHook<unknown> | VoidHook<unknown[]> | OtherHook | undefined;
     /** Common authentication hooks */
     beforeAuth?: ChainedHook<[Request, Response]>;
     afterAuth?: ChainedHook<[Request, Response]>;
     /** Organization hooks */
-    getOrganisationTop?: ChainedHook<[
-        Request | undefined,
-        AttributesList | null
-    ]>;
+    getOrganisationTop?: ChainedHook<[Request | undefined, AttributesList]>;
+    /**
+     * SCIM plugin hooks
+     *
+     * The `create` and `update` hooks are chained and can mutate the resource
+     * about to be written; the `done` ones are notified once it is written.
+     * `scimgroupcreate` gets the group's base beside the request, which is
+     * always there: a group is created through the API.
+     */
+    scimusercreate?: ChainedHook<[ScimUser, Request?]>;
+    scimusercreatedone?: VoidHook<[ScimUser]>;
+    scimuserupdate?: ChainedHook<[string, ScimUser, Request?]>;
+    scimuserupdatedone?: VoidHook<[string, ScimUser]>;
+    scimuserdelete?: ChainedHook<[string, Request?]>;
+    scimuserdeletedone?: VoidHook<[string]>;
+    /** `[group, request, base]` */
+    scimgroupcreate?: ChainedHook<[ScimGroup, Request, string]>;
+    scimgroupcreatedone?: VoidHook<[ScimGroup]>;
+    scimgroupupdate?: ChainedHook<[string, ScimGroup, Request?]>;
+    scimgroupupdatedone?: VoidHook<[string, ScimGroup]>;
+    scimgroupdelete?: ChainedHook<[string, Request?]>;
+    scimgroupdeletedone?: VoidHook<[string]>;
+    scimbulkdone?: VoidHook<[BulkResponse]>;
+    /**
+     * A delete asked of an entry that is already a tombstone. Fired
+     * synchronously with the request that asked it: whoever replays deletions
+     * records it from there. `[dn, entry, context]`.
+     */
+    twakedeletionreplay?: (dn: string, entry: AttributesList, context: ChangeContext) => MaybePromise<void>;
 }
+/**
+ * The prefix of a flat entity's hooks, as `abstract/ldapFlat.ts` builds it:
+ * `ldap${entity.name}`. They are `{prefix}add`, `{prefix}adddone` and so on,
+ * one convention each, as the shared hook of the same suffix declares it,
+ * plus `{prefix}move` before an entry is moved. A plugin watching one
+ * declares them beside its other hooks.
+ */
+export type FlatHookPrefix = `ldap${string}`;

package/dist/src/lib/authz/base.d.ts

@@ -10,8 +10,9 @@ import type { SearchOptions } from 'ldapts';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import type { BranchPermissions } from '../../config/args';
+import type { Hooks } from '../../hooks';
 import { type DmRequest } from '../auth/base';
-import type { AttributesList, ModifyRequest, SearchResult } from '../ldapActions';
+import type { ModifyRequest } from '../ldapActions';
 /**
  * The rule of the most specific configured branch holding `target`.
  *
@@ -311,7 +312,7 @@ export default abstract class AuthzBase extends DmPlugin {
      *
      * @param req the request being authorized, which carries an identity
      * @returns the resolved user, or null when the policy is to allow it
-     * @throws ForbiddenError when the policy is to deny it
+     * @throws AuthzRefusedError when the policy is to deny it
      */
     /** Said once: a rule keyed on a value the authenticator did not publish. */
     private fallbackWarned;
@@ -382,53 +383,5 @@ export default abstract class AuthzBase extends DmPlugin {
     /**
      * Common hooks for all authorization plugins
      */
-    hooks: {
-        /**
-         * A rename moves the entry an identity resolves to, so what was
-         * resolved is dropped.
-         *
-         * `authzLinid1` keys its permissions on the administrator's DN: renamed
-         * or moved, they resolve to a DN no organization names any more, and
-         * every operation of theirs is refused until the TTL runs out. The
-         * whole map goes rather than one key, since what is cached is
-         * identity → DN and the hook carries DNs: a handful of lookups is
-         * cheaper than working out which identity moved.
-         */
-        ldaprenamedone: () => void;
-        /**
-         * A delete removes the entry an identity resolves to, exactly as a
-         * rename moves it, so what was resolved is dropped the same way.
-         *
-         * An administrator deleted through the API is, for `authzLinid1`, still
-         * resolved to the former DN where the organization still names them:
-         * their session keeps its rights until the TTL runs out. Like the rename
-         * hook, the whole map goes rather than one key — the hook carries the
-         * deleted DN, and the cache keys identities, so a handful of lookups is
-         * cheaper than working out which identity the DN held.
-         */
-        ldapdeletedone: () => void;
-        ldapmodifyrequest: ([dn, changes, opNumber, req]: [string, ModifyRequest, number, DmRequest?]) => Promise<[string, ModifyRequest, number, DmRequest?]>;
-        ldapaddrequest: ([dn, entry, req]: [string, AttributesList, DmRequest?]) => Promise<[string, AttributesList, DmRequest?]>;
-        ldapsearchrequest: ([base, opts, req]: [string, SearchOptions, DmRequest?]) => Promise<[string, SearchOptions, DmRequest?]>;
-        /**
-         * Drop what this caller may not read from a search it was granted.
-         *
-         * Judged by branch, the search was granted on its base: each entry is
-         * kept only where the caller may read it, a rule narrower than the base
-         * refusing part of what it holds. Judged by attachment, the accounts
-         * attached outside the branches this caller manages are dropped.
-         *
-         * Runs after the cache and carries the request, so what one caller may
-         * not see never reaches another. An entry with no organization link —
-         * an organization, a group, a nomenclature value — is left alone: those
-         * are the reference data every administrator reads.
-         *
-         * So is an entry attached to the transit branch: it is waiting for an
-         * administrator to claim it.
-         */
-        ldapsearchfilter: ([result, req, opts]: [SearchResult, DmRequest?, SearchOptions?]) => Promise<[SearchResult, DmRequest?, SearchOptions?]>;
-        getOrganisationTop: ([req, defaultTop]: [DmRequest | undefined, AttributesList | null]) => Promise<[DmRequest | undefined, AttributesList | null]>;
-        ldaprenamerequest: ([oldDn, newDn, req]: [string, string, DmRequest?]) => Promise<[string, string, DmRequest?]>;
-        ldapdeleterequest: ([dn, req]: [string | string[], DmRequest?]) => Promise<[string | string[], DmRequest?]>;
-    };
+    hooks: Hooks;
 }

package/dist/src/lib/authz/composition.d.ts

@@ -5,8 +5,8 @@
  * How authorization plugins loaded together compose, and the configurations
  * where that composition is nobody's decision.
  *
- * Every plugin judging LDAP operations registers the same hooks, and
- * `launchHooksChained` runs them all: two of them compose as an AND, the
+ * Every plugin judging LDAP operations registers the same hooks, and the
+ * chain runs them all: two of them compose as an AND, the
  * first refusal winning. That is a sound rule when it is meant. It is a
  * refusal nobody can explain when it is not — `authzPerBranch` beside
  * `authzDynamic` judges a machine token by a branch configuration written

package/dist/src/lib/entitySchema/validator.d.ts

@@ -22,19 +22,76 @@ export declare class EntityValidator {
     private readonly deps;
     constructor(schema: Schema | undefined, deps: EntityValidatorDeps);
     /**
-     * Check a new entry, then convert it in place for the directory.
+     * Check a new entry, then convert it for the directory. Every attribute
+     * the schema declares is named as the schema does, a form the defaults,
+     * the required check and the conversion all read.
      *
      * @param entry entry as the client sent it, `objectClass` included
+     * @returns the entry to write: the one given, or a copy under the schema's
+     *   spellings
      */
-    validateNew(entry: AttributesList): Promise<void>;
+    validateNew(entry: AttributesList): Promise<AttributesList>;
     /**
-     * Check the parts of a change, then convert them in place. No value under
-     * a name is the empty list for the directory layer, which clears the
-     * attribute in a `replace` and refuses it in an `add`.
+     * Check the parts of a change, then convert them. Under a name the schema
+     * declares, no value becomes the empty list, which clears the attribute
+     * in a `replace` and is refused in an `add`; under a name it does not
+     * declare, a `null` is dropped from an `add` and becomes that empty list
+     * in a `replace`.
      *
      * @param changes change as the client sent it
+     * @returns the same change, under the schema's spellings
      */
-    validateChanges(changes: ModifyRequest): Promise<void>;
+    validateChanges(changes: ModifyRequest): Promise<ModifyRequest>;
+    /**
+     * Name every key the schema declares as the schema does, and refuse two
+     * keys naming one attribute. The conversion, the required check and the
+     * defaults look a declared attribute up by its own name: a field they
+     * would leave out is one the client sent under another case or with a
+     * `;binary` option.
+     *
+     * @returns the same attributes, renamed: the map itself when nothing
+     *   changes, a copy renamed otherwise
+     * @throws BadRequestError when two keys name the same attribute
+     */
+    private renameDeclared;
+    /**
+     * {@link renameDeclared} on a list of names, such as a `delete`.
+     *
+     * Two names of one attribute are refused as the routes refuse them: as
+     * the schema declares it, or as this server knows the attribute by its
+     * name, which makes `l;binary` and `L` one attribute.
+     */
+    private renameDeclaredNames;
+    /**
+     * The attribute a name holds, case and option aside: the option is a
+     * transfer syntax, and `l;binary` is the `l` a plain `L` names.
+     */
+    private attributeIdentity;
+    /**
+     * The schema's spelling of a declared attribute, with the `;binary`
+     * option, the only one a write takes, written as the directory writes it.
+     */
+    private schemaSpelling;
+    /**
+     * Drop, in place, the keys a creation or an `add` carries with `null` or
+     * `undefined` under a name the schema does not declare. A declared
+     * attribute is left to the schema, which turns no value into the empty
+     * list, refused for a `required` one; an undeclared one has no such step,
+     * and without a schema none exists. The write would otherwise carry
+     * `[null]`, which ldapts cannot send.
+     */
+    private dropUndeclaredEmpty;
+    /**
+     * Check every value of a creation or of a part of a change, then write the
+     * shape each one is stored in, in place: no value becomes the empty list,
+     * which clears the attribute in a `replace`. A value the schema does not
+     * declare is left as sent on a change, and on a creation as the directory
+     * layer takes it.
+     *
+     * @param values entry of a creation, or `add` / `replace` of a change
+     * @param part the part of a change, undefined for a creation
+     */
+    private checkValues;
     /**
      * Check one value against its attribute's rules: its shape, then the
      * entries a pointer names, then the pattern.

package/dist/src/lib/errors.d.ts

@@ -59,6 +59,62 @@ export declare const errorBody: (err: unknown, message: string) => {
 export declare class ForbiddenError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * An authorization plugin's refusal.
+ *
+ * Its message is for the operator, not for the client: it names the model
+ * and the branch it judged, which the caller may not know of. Its class is
+ * what says an authorization plugin refused, so the 403 is recognised
+ * through the `new Error(\`…\`, { cause })` wrappers along the way — see
+ * {@link isAuthzRefusal} — and the client is told {@link AUTHZ_REFUSED}.
+ */
+export declare class AuthzRefusedError extends ForbiddenError {
+    /**
+     * Read instead of the class and the name: a plugin loaded from `dist` holds
+     * another copy of this module, where `instanceof` answers false, and a
+     * subclass may replace `name`.
+     */
+    readonly authzRefusal: true;
+    constructor(message: string);
+}
+/**
+ * Every error in a chain of `cause`s, the outermost first.
+ *
+ * A plugin wrapping what the directory or an authorization hook threw as
+ * `new Error(\`…\`, { cause: err })` keeps the reason and what it carries:
+ * its class, its status, the database's refusal. The serializers read the
+ * whole chain rather than the wrapper alone.
+ *
+ * @param err what was thrown, which need not be an error
+ * @returns the errors of the chain, the outermost first
+ */
+export declare const errorChain: (err: unknown) => Error[];
+/**
+ * Whether an error is, or wraps through `cause`, an authorization plugin's
+ * refusal.
+ *
+ * Read by the `authzRefusal` marker rather than by class: a plugin loaded
+ * from `dist` while its caller runs from `src` throws a `AuthzRefusedError`
+ * whose `instanceof` answers false, and a subclass that replaces `name`
+ * would escape a name test — the refusal would then be answered as the
+ * wrapper's own error.
+ *
+ * @param err what was thrown
+ * @returns true for a refusal, or for an error wrapping one
+ */
+export declare const isAuthzRefusal: (err: unknown) => boolean;
+/**
+ * The status a thrown thing is answered with.
+ *
+ * The first error from the outside that names one decides: a wrapper names
+ * none, so the error it wraps is read; a layer that translates an inner error
+ * keeps its own status. `statusCode` is the convention of this module, while
+ * Express's router sets `status` alone on the errors it throws.
+ *
+ * @param err what was thrown
+ * @returns its status code, 500 when it names none
+ */
+export declare const statusCodeOf: (err: unknown) => number;
 /**
  * An identity that names more than one directory entry.
  *
@@ -69,7 +125,7 @@ export declare class ForbiddenError extends HttpError {
  * rather than a `null`: a `null` resolution is what
  * `--authz-unresolved-user allow` lets through unchecked.
  */
-export declare class AmbiguousIdentityError extends ForbiddenError {
+export declare class AmbiguousIdentityError extends AuthzRefusedError {
     identity: string;
     count: number;
     constructor(identity: string, count: number);

package/dist/src/lib/expressFormatedResponses.d.ts

@@ -1,9 +1,6 @@
-/**
- * Standard express responses and express utilities
- * @author Xavier Guimard <xguimard@linagora.com>
- */
 import type { Request, Response } from 'express';
 import type winston from 'winston';
+import { type Refusal } from './errors';
 /**
  * Install the logger, or remove it: a test restores the state it found,
  * which before any `DM` is none.
@@ -21,9 +18,47 @@ export declare const getLogger: () => winston.Logger | undefined;
  */
 export declare const setDebug: (debug: boolean) => void;
 /**
- * The body of a 5xx answer, for the error middleware of `DM` and
- * `serverError` alike. The failure is for the logs: the message names it
- * only under `--debug`.
+ * The sentence a client is told of a client error: an authorization
+ * plugin's refusal says nothing of the branch it judged.
+ *
+ * Any other client error keeps the sentence of the outermost error, the one
+ * the route threw when it gave up: it says what the caller's request was
+ * about, which the `HttpError` several layers down does not.
+ *
+ * @param err what was thrown
+ * @returns the sentence to answer
+ */
+export declare const clientMessageOf: (err: unknown) => string;
+/**
+ * The message of a thrown thing, read the way the log reads it.
+ *
+ * @param err what was thrown
+ * @returns its message, or the value as a string
+ */
+export declare const messageOf: (err: unknown) => string;
+/**
+ * What an error is answered with, for the error middleware of `DM` and
+ * `serverError` alike: one status and one body, wherever the handler called
+ * a helper or threw.
+ *
+ * An authorization plugin's refusal loses its status when a plugin wraps it
+ * as a plain `Error`; it is still a 403, whatever the wrapper says. The
+ * failure of a 5xx is for the logs, and is named in the body only under
+ * `--debug`.
+ *
+ * @param err what failed
+ * @param debug whether to name a failure in the answer
+ * @returns the status and body to answer
+ */
+export declare const errorResponse: (err: unknown, debug?: boolean) => {
+    status: number;
+    body: {
+        error: string;
+    } & Partial<Refusal>;
+};
+/**
+ * The body of a 5xx answer, for every status answered when the failure is
+ * the server's: the message names the failure only under `--debug`.
  *
  * @param err what failed
  * @param debug whether to name the failure; `serverError`'s setting by default
@@ -34,6 +69,13 @@ export declare const serverErrorBody: (err: unknown, debug?: boolean) => {
 };
 export declare const tryMethod: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
 export declare const tryMethodData: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
+/**
+ * The answer of a route that changed something and returned nothing: the
+ * shape every write route declares as its 200.
+ */
+export declare const WriteResponse: import("@sinclair/typebox").TObject<{
+    success: import("@sinclair/typebox").TBoolean;
+}>;
 export declare const ok: (res: Response, data?: object) => void;
 export declare const created: (res: Response, data?: object) => void;
 export declare const noContent: (res: Response) => void;