ldap-rest 1.2.1 → 1.3.0

package/dist/src/abstract/ldapFlat.d.ts

@@ -1,12 +1,3 @@
-/**
- * @module abstract/ldapFlat
- * @author Xavier Guimard <xguimard@linagora.com>
- *
- * Abstract class to manage LDAP entries in a flat branch
- * - add/delete entries
- * - modify entries
- * - validate with schema
- */
 import type { Express, Request, Response } from 'express';
 import type { DM } from '../bin';
 import type ldapActions from '../lib/ldapActions';
@@ -210,6 +201,26 @@ export interface LdapFlatConfig {
  *     dn: uid=bob,ou=users,dc=example,dc=com
  *     referencesUpdated: 3
  */
+export declare const FlatListQuery: import("@sinclair/typebox").TObject<{
+    match: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    attribute: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    attributes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export declare const FlatEntryParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+}>;
+export declare const FlatMoveBody: import("@sinclair/typebox").TObject<{
+    targetOrgDn: import("@sinclair/typebox").TString;
+}>;
+export declare const FlatMoveResponse: import("@sinclair/typebox").TObject<{
+    success: import("@sinclair/typebox").TBoolean;
+    departmentPath: import("@sinclair/typebox").TString;
+    departmentLink: import("@sinclair/typebox").TString;
+}>;
+export declare const FlatRenameBody: import("@sinclair/typebox").TObject<{
+    newId: import("@sinclair/typebox").TString;
+}>;
 export default abstract class LdapFlat extends DmPlugin {
     base: string;
     ldap: ldapActions;
@@ -220,6 +231,12 @@ export default abstract class LdapFlat extends DmPlugin {
     singularName: string;
     pluralName: string;
     hookPrefix: string;
+    /** `hookBus`, raising this entity's own hooks */
+    private readonly ownHooks;
+    /**
+     * @param server the server
+     * @param config the entity, its hook prefix included
+     */
     constructor(server: DM, config: LdapFlatConfig);
     /**
      * Attributes never sent back over the API. A manager may reset a password
@@ -421,6 +438,7 @@ export default abstract class LdapFlat extends DmPlugin {
         truncated: boolean;
     }>;
     searchEntriesByName(name: string, partial?: boolean, attrs?: string[]): Promise<LdapList>;
-    validateNewEntry(dn: string, entry: AttributesList): Promise<boolean>;
+    /** @returns the entry to write, under the schema's spellings */
+    validateNewEntry(dn: string, entry: AttributesList): Promise<AttributesList>;
     validateChanges(dn: string, changes: ModifyRequest): Promise<boolean>;
 }

package/dist/src/abstract/plugin.d.ts

@@ -3,25 +3,28 @@
  * @author Xavier Guimard <xguimard@linagora.com>
  */
 import type { Express } from 'express';
-import fetch, { type RequestInit, type Response } from 'node-fetch';
 import type winston from 'winston';
 import type { Config, DM } from '../bin';
 import type { Hooks, MaybePromise } from '../hooks';
+import type HookBus from '../lib/hookBus';
 import type { HealthStatus } from '../lib/health';
+import { type OptionsOf, type OptionSet } from '../config/options';
 export { asyncHandler, escapeDnValue, unescapeDnValue, escapeLdapFilter, validateDnValue, } from '../lib/utils';
+export { defineRoute, registeredRoutes } from '../lib/route';
 export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UriTooLongError, TooManyRequestsError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, } from '../lib/errors';
 export type { HealthStatus };
 export type Role = 'auth' | 'authz' | 'protect' | 'api' | 'logging' | 'demo' | 'consistency' | 'configurable';
 export default abstract class DmPlugin {
+    /** Options this plugin declares, see `docs/plugin-development/options.md` */
+    static optionDefinitions: OptionSet;
     /**
      * Properties inherited from parent (DM)
      */
     server: DM;
     config: Config;
+    hookBus: HookBus;
     logger: winston.Logger;
-    registeredHooks: {
-        [K in keyof Hooks]?: Function[];
-    };
+    registeredHooks: Hooks;
     /**
      * Interfaces
      */
@@ -76,12 +79,14 @@ export default abstract class DmPlugin {
      * Call another service: `fetch`, timed into the outbound metrics under
      * this plugin's name, see `docs/usage/operations.md#metrics`.
      */
-    protected fetch(url: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response>;
+    protected fetch(url: Parameters<typeof globalThis.fetch>[0], init?: RequestInit): Promise<Response>;
     /**
      * Constructor
      * @param server DM object
      */
     constructor(server: DM);
+    /** Values of the options this plugin declares, read and checked */
+    options<T extends OptionSet>(definitions: T): OptionsOf<T>;
     /**
      * Uniq ID, to be used when calling hooks
      *

package/dist/src/abstract/twakePlugin.d.ts

@@ -9,6 +9,18 @@ import type { DM } from '../bin';
 import { type HealthStatus } from '../lib/health';
 import type { AttributesList } from '../lib/ldapActions';
 import DmPlugin, { type Role } from './plugin';
+/** What a Twake plugin needs to reach its WebAdmin API */
+export interface TwakeConnection {
+    url: string;
+    token: string;
+    concurrency: number;
+    /** Option holding the URL, named in the startup error when it is empty */
+    urlOption: string;
+    /** Option holding the token, named in the warning when it is empty */
+    tokenOption: string;
+    /** Option holding the concurrency, named when it is not a positive integer */
+    concurrencyOption: string;
+}
 /**
  * Abstract base class for all Twake-related plugins (James, Calendar, Matrix, etc.)
  * Consolidates common patterns for HTTP communication with Twake WebAdmin APIs
@@ -26,11 +38,9 @@ export declare abstract class TwakePlugin extends DmPlugin {
     /**
      * Constructor - initializes common Twake plugin configuration
      * @param server DM server instance
-     * @param urlConfig Configuration key for WebAdmin URL
-     * @param tokenConfig Configuration key for WebAdmin token
-     * @param concurrencyConfig Configuration key for concurrency limit
+     * @param connection WebAdmin URL, token and concurrency
      */
-    constructor(server: DM, urlConfig: string, tokenConfig: string, concurrencyConfig: string);
+    constructor(server: DM, connection: TwakeConnection);
     /**
      * Create HTTP headers with optional Authorization token
      * @param contentType Optional Content-Type header value

package/dist/src/bin/index.d.ts

@@ -19,10 +19,11 @@ import type { Hooks } from '../hooks';
 import ldapActions from '../lib/ldapActions';
 import type DmPlugin from '../abstract/plugin';
 import AuthBase from '../lib/auth/base';
+import HookBus from '../lib/hookBus';
 export type { Config };
 export * from '../lib/utils';
 export { asyncHandler } from '../lib/utils';
-export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UriTooLongError, TooManyRequestsError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, } from '../lib/errors';
+export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, AuthzRefusedError, NotFoundError, ConflictError, UriTooLongError, TooManyRequestsError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, } from '../lib/errors';
 /**
  * @class DM
  */
@@ -33,9 +34,13 @@ export declare class DM {
     /** The listener, once `run()` opened it; shared by the `withConfig` views */
     get server(): import('http').Server | undefined;
     set server(server: import('http').Server | undefined);
-    hooks: {
-        [K in keyof Hooks]?: Function[];
-    };
+    /**
+     * What each hook's subscribers do, as a plugin declares them. The type
+     * names every hook: raising or subscribing to one goes through `hookBus`,
+     * which checks the arguments.
+     */
+    hooks: Hooks;
+    readonly hookBus: HookBus;
     loadedPlugins: {
         [key: string]: DmPlugin;
     };
@@ -87,6 +92,8 @@ export declare class DM {
      * whose name is taken. A Map, so that `withConfig` views share it.
      */
     private readonly pluginLoads;
+    /** CLI arguments no declared option matched, reported after the logger exists */
+    private readonly unknownCliOptions;
     /**
      * The request hooks of the authorization plugins, which `registerPlugin`
      * keeps ahead of every other plugin's. See {@link AUTHZ_FIRST_HOOKS}.
@@ -123,6 +130,12 @@ export declare class DM {
      * @returns a server view backed by this instance
      */
     withConfig(config: Config): DM;
+    /**
+     * Name the CLI arguments and `DM_*` variables nothing declares, among the
+     * plugins `--plugins` loaded and their `optionDefinitions`. A host that
+     * registers its own plugins after `ready` is not covered.
+     */
+    private reportUnknownOptions;
     /**
      * Mount the authentication dispatcher, once, before the first plugin that
      * can register a route.

package/dist/src/config/args.d.ts

@@ -1,8 +1,6 @@
 import type { AttributesList } from '../lib/ldapActions';
 import type { ConfigTemplate } from '../lib/parseConfig';
-/** The headers `core/static` sends unless told otherwise: no framing by another site */
-export declare const STATIC_CSP = "frame-ancestors 'self'";
-export declare const STATIC_FRAME_OPTIONS = "SAMEORIGIN";
+export { STATIC_CSP, STATIC_FRAME_OPTIONS } from '../plugins/static.options';
 export interface BranchPermissions {
     read?: boolean;
     write?: boolean;
@@ -34,6 +32,7 @@ export interface Config {
     log_level: 'error' | 'warn' | 'notice' | 'info' | 'debug';
     shutdown_timeout?: number;
     debug: boolean;
+    strict_options?: boolean;
     logger: 'console' | 'file';
     log_file?: string;
     api_prefix: string;
@@ -364,7 +363,6 @@ export interface Config {
     scim_bulk_max_payload_size?: number;
     scim_etag?: boolean;
     scim_base_url?: string;
-    [key: string]: string | string[] | boolean | number | AttributesList | AuthConfig | undefined;
 }
 /**
  * Config arguments

package/dist/src/config/options.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Configuration options declared by the code that reads them.
+ *
+ * A plugin describes its options next to its implementation with
+ * {@link defineOptions}; `src/config/args.ts` concatenates the declarations so
+ * the parser sees the same entries it always did. {@link readOptions} gives a
+ * plugin typed values, with the defaults applied and the value checked once.
+ *
+ * See `docs/plugin-development/options.md`.
+ */
+import { type ArrayKind, type ConfigEntry, type ConfigTemplate } from '../lib/parseConfig';
+import type { Config } from './args';
+export type OptionType = 'string' | 'number' | 'boolean' | 'array' | 'json';
+export interface OptionSpec<T> {
+    readonly type: OptionType;
+    /** Environment variable the option reads when the CLI does not set it */
+    readonly env?: string;
+    /** Value kept when neither the CLI nor the environment sets the option */
+    readonly default?: T;
+    /** Refuse an empty value rather than read it as unset */
+    readonly required?: boolean;
+    /**
+     * A string option whose empty value means something: keep it instead of
+     * reading the declared default, as an empty environment or CLI value does.
+     */
+    readonly emptyIsValue?: boolean;
+}
+export interface StringOption extends OptionSpec<string> {
+    readonly type: 'string';
+    /** Values the option accepts, when it is a closed set */
+    readonly choices?: readonly string[];
+}
+export interface StringOrFalseOption extends OptionSpec<string | false> {
+    readonly type: 'string';
+    readonly allowFalse: true;
+}
+export interface NumberOption extends OptionSpec<number> {
+    readonly type: 'number';
+    readonly min?: number;
+    readonly max?: number;
+}
+export interface BooleanOption extends OptionSpec<boolean> {
+    readonly type: 'boolean';
+}
+export interface ArrayOption extends OptionSpec<string[]> {
+    readonly type: 'array';
+    /** CLI name of the plural form, without the leading `--` */
+    readonly plural?: string;
+    /** How a comma, space or semicolon separated value splits, see ArrayKind */
+    readonly kind?: ArrayKind;
+}
+export interface JsonOption<T> extends OptionSpec<T> {
+    readonly type: 'json';
+}
+export type OptionSet = Record<string, OptionSpec<unknown>>;
+/** The typed values {@link readOptions} returns for a set of declarations */
+export type OptionsOf<T extends OptionSet> = {
+    [K in keyof T]: T[K] extends OptionSpec<infer V> ? V : never;
+};
+/**
+ * A set of options, keyed by their `Config` name (`scim_max_results` for
+ * `--scim-max-results`). Identity function: its only job is to keep the
+ * literal types of the declarations.
+ */
+export declare function defineOptions<T extends OptionSet>(options: T): T;
+export declare const opt: {
+    string: (options?: Omit<StringOption, "type">) => StringOption;
+    number: (options?: Omit<NumberOption, "type">) => NumberOption;
+    boolean: (options?: Omit<BooleanOption, "type">) => BooleanOption;
+    array: (options?: Omit<ArrayOption, "type">) => ArrayOption;
+    stringOrFalse: (options?: Omit<StringOrFalseOption, "type" | "allowFalse">) => StringOrFalseOption;
+    json: <T = Record<string, unknown>>(options?: Omit<JsonOption<T>, "type">) => JsonOption<T>;
+};
+/**
+ * The parser entries a set of declarations amounts to. `args.ts` concatenates
+ * them with the global options and the other plugins' declarations.
+ */
+export declare function toConfigEntries(options: OptionSet): ConfigEntry[];
+/**
+ * `DM_*` variables no declared option reads. Test-only variables are left
+ * out: a suite sets its own infrastructure through the same prefix.
+ */
+export declare function unknownEnvironmentOptions(entries: ConfigTemplate, env?: Record<string, string | undefined>, extra?: OptionSet[]): string[];
+/**
+ * Read a plugin's options from a parsed configuration, applying the declared
+ * defaults and checking the values. Called once per instance by
+ * `DmPlugin.options()`.
+ */
+export declare function readOptions<T extends OptionSet>(options: T, config: Config | Record<string, unknown>, parsedKeys?: ReadonlySet<string>): OptionsOf<T>;

package/dist/src/config/schema.d.ts

@@ -75,6 +75,16 @@ export declare function localizedText(text: LocalizedText | undefined, language?
  * @returns the message
  */
 export declare function invalidValueMessage(name: string, attr: SchemaAttribute | undefined): string;
+/**
+ * Refusal of a value longer than its attribute accepts, for a
+ * `BadRequestError`. Said apart from {@link invalidValueMessage}: the value
+ * is not malformed, it is longer than the attribute may hold.
+ *
+ * @param name attribute name
+ * @param maxLength the length it may not exceed
+ * @returns the message
+ */
+export declare function tooLongMessage(name: string, maxLength: number): string;
 /** Roles the core itself looks for. See {@link SchemaRole}. */
 export declare const CORE_ROLES: readonly ["identifier", "displayName", "primaryEmail", "emailAliases", "emailQuota", "organizationLink", "organizationPath", "members", "owners", "accountStatus", "password", "passwordReset", "accountExpiry", "domainLink", "domainName"];
 /**
@@ -142,10 +152,19 @@ export interface SchemaAttribute {
         test?: string | RegExp;
         hint?: LocalizedText;
         branch?: string[];
+        /** Longest value, in UTF-16 code units, before `test` runs on it */
+        maxLength?: number;
     };
     default?: AttributeValue;
     required?: boolean;
     test?: string | RegExp;
+    /**
+     * Longest value, in UTF-16 code units, `test` is asked to judge: a longer one is
+     * refused before the pattern reads it. Without it, the length is
+     * {@link DEFAULT_MAX_LENGTH}; an attribute holding longer values declares
+     * it here, the reason being in `docs/client-development/schemas/README.md`.
+     */
+    maxLength?: number;
     /**
      * Plain-language description of `test`, shown to the user *before* they get
      * a value wrong — "Expected pattern 999 9999". It travels with the
@@ -334,6 +353,10 @@ export declare function modifiedAttributeNames(body: {
  * written as text where the schema declares one, a boolean as LDAP's
  * `TRUE` / `FALSE`, and anything else is refused.
  *
+ * The attribute is read as a request names it, under any case and with or
+ * without a `;binary` option: the value is converted by its type, as the
+ * validator accepted it.
+ *
  * @param schema schema of the entry, if any
  * @param field attribute name
  * @param value value as the client sent it
@@ -391,15 +414,41 @@ export declare function withoutAttributes<T extends object>(entry: T, hidden: Se
  * @throws BadRequestError naming the first DN that breaks a rule
  */
 export declare function checkDnValues(field: string, attr: SchemaAttribute, value: AttributeValue, entryExists: (dn: string) => Promise<boolean>): Promise<void>;
+/**
+ * Longest value a pattern is asked to judge when the schema declares no
+ * `maxLength`. See `docs/client-development/schemas/README.md`.
+ */
+export declare const DEFAULT_MAX_LENGTH = 4096;
+/**
+ * The length a value is judged against: `maxLength` on the attribute, else
+ * the one on its `items`, else {@link DEFAULT_MAX_LENGTH}.
+ */
+export declare function maxLengthOf(attr: SchemaAttribute | undefined): number;
 /**
  * Tell whether every value of an attribute matches its pattern: `test`, or
  * `items.test` for the elements of an array.
  *
+ * A value longer than {@link maxLengthOf} is refused without running the
+ * pattern: see {@link SchemaAttribute.maxLength}.
+ *
  * @param attr schema definition
  * @param value value submitted
- * @returns false when one value does not match
+ * @returns false when one value does not match, or is too long
  */
 export declare function matchesPattern(attr: SchemaAttribute, value: AttributeValue): boolean;
+/**
+ * The value past the length its attribute accepts, if one is: what a refusal
+ * says, where the pattern would only have said the value is wrong.
+ *
+ * The default length applies to an attribute carrying a pattern, which it
+ * keeps within what the pattern was written for; an attribute without one is
+ * bounded only by the `maxLength` its schema declares.
+ *
+ * @param attr schema definition
+ * @param value value submitted
+ * @returns the too long value, or undefined when none is
+ */
+export declare function tooLongValue(attr: SchemaAttribute, value: AttributeValue): AttributeValue | undefined;
 /**
  * Refuse a payload naming an attribute the server owns.
  *

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