ldap-rest 1.2.0 → 1.3.0

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,61 @@ 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.
+ *
+ * @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 +124,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;

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

@@ -0,0 +1,226 @@
+/**
+ * The hooks of the server, typed by `Hooks`, with one calling convention per
+ * kind.
+ *
+ * The three kinds are told apart by what their subscriber answers:
+ * chained hooks get a value and pass it — possibly changed — along the
+ * chain; notified hooks answer nothing, are not waited for, and their
+ * failures are logged; several hooks answer a value each.
+ *
+ * @see docs/plugin-development/hooks.md
+ */
+import type { Hooks } from '../hooks';
+export type HookFn = Function;
+/** A promise, or the value itself */
+type Settled<T> = T extends Promise<infer P> ? P : T;
+/** Whether `F` answers nothing: `void`, or a promise of it */
+export type AnswersVoid<F> = [
+    Settled<F extends (...args: never[]) => infer R ? R : never>
+] extends [void | undefined] ? true : false;
+/** The values of `Hooks` a chain threads: the ones whose answer is a value */
+export type ChainedName = {
+    [K in keyof Hooks]-?: AnswersVoid<NonNullable<Hooks[K]>> extends true ? never : K;
+}[keyof Hooks];
+/** The `Hooks` a notification fires: the ones whose subscriber answers nothing */
+export type NotifiedName = Exclude<keyof Hooks, ChainedName>;
+/** A chained hook is declared with the value it threads */
+export type ChainedNameOf<K extends keyof Hooks> = K extends ChainedName ? K : never;
+/** The arguments a hook expects */
+export type Args<K extends keyof Hooks> = NonNullable<Hooks[K]> extends (...args: infer A) => unknown ? A : never;
+/** What a chained hook threads */
+export type ChainedValue<K extends keyof Hooks> = NonNullable<Hooks[K]> extends (arg: infer A) => unknown ? A : never;
+/**
+ * Record the plugin a hook function belongs to.
+ *
+ * @param fn the registered function
+ * @param plugin the plugin's instance name
+ * @param hook the hook it is registered under
+ */
+export declare const recordHookOwner: (fn: HookFn, plugin: string, hook: string) => void;
+/**
+ * The plugin a hook function belongs to, and the hook it is registered
+ * under, when `registerPlugin` registered it.
+ *
+ * @param fn a hook function
+ * @returns its plugin's instance name and hook name, or undefined
+ */
+export declare const hookOwner: (fn: HookFn) => {
+    plugin: string;
+    hook: string;
+} | undefined;
+/**
+ * Run a hook under its plugin's name and its own, for the lines it logs.
+ *
+ * @param hook the registered function
+ * @param fn its run
+ * @returns what `fn` returns
+ */
+export declare const runAsHookOwner: <T>(hook: HookFn, fn: () => T) => T;
+/**
+ * A hook's list, as `server.hooks` spells it: `undefined` when nothing is
+ * subscribed, a function for one subscriber, a list for several, and
+ * anything else when a test writes a list through the hook and walks it.
+ */
+export type HookValue<K extends keyof Hooks = keyof Hooks> = Hooks[K] | Function[] | undefined;
+/** The functions a subscriber value holds, one or many */
+export declare const asHooks: <K extends keyof Hooks>(value: HookValue<K>) => HookFn[];
+/**
+ * How a flat entity raises its own hooks, see `abstract/ldapFlat.ts`: the
+ * prefix it names them under, added to the suffix of each. They are not
+ * `Hooks`' own, see {@link FlatHookPrefix}.
+ */
+export interface FlatHookBus {
+    /** Thread a value through `{prefix}{suffix}`, as {@link HookBus.chain} */
+    chain<T>(suffix: string, value: T): Promise<T>;
+    /** Notify `{prefix}{suffix}`, as {@link HookBus.notify} */
+    notify(suffix: string, ...args: unknown[]): void;
+}
+export default class HookBus implements FlatHookBus {
+    /**
+     * What `server.hooks` holds, shared by reference. A plugin reaching it
+     * directly is not told by its type whether the hook exists, nor how it
+     * is called; this bus is.
+     */
+    private readonly hooks;
+    private readonly tracked;
+    /**
+     * @param hooks the server's hook lists, shared by reference
+     */
+    constructor(hooks: {
+        [K in keyof Hooks]?: HookValue<K>;
+    });
+    /** Whether anything is subscribed to a hook */
+    has(name: keyof Hooks): boolean;
+    /**
+     * The subscribers of a hook, in the order they run.
+     *
+     * @param name the hook
+     * @returns its subscribers, empty when nothing subscribed
+     */
+    subscribers(name: keyof Hooks): readonly HookFn[];
+    /**
+     * Subscribe a function to a hook, or forget its subscribers when given
+     * none, as a plugin declaring `hooks` would.
+     *
+     * @param name the hook
+     * @param fn what to run, none to unsubscribe every subscriber
+     */
+    set<K extends keyof Hooks>(name: K, ...fn: NonNullable<Hooks[K]>[]): void;
+    /**
+     * Add a subscriber to a hook, after the ones already there.
+     *
+     * @param name the hook
+     * @param fn what to run
+     */
+    subscribe<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>): void;
+    /**
+     * Put a subscriber at a given place in a hook's list, as
+     * `registerPlugin` does for an authorization hook.
+     *
+     * @param name the hook
+     * @param fn what to run
+     * @param at its place, the end when past it
+     */
+    insert<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>, at: number): void;
+    /**
+     * Remove a subscriber from a hook, wherever it sits.
+     *
+     * @param name the hook
+     * @param fn the subscriber
+     */
+    unsubscribe<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>): void;
+    /**
+     * Move a subscriber to the end of its hook's list, keeping it registered,
+     * for a plugin that must run after every other one.
+     *
+     * @param name the hook
+     * @param hook the subscriber
+     * @returns whether it was subscribed to the hook
+     */
+    toLast(name: keyof Hooks, hook: HookFn): boolean;
+    /**
+     * Thread a value through every subscriber of a chained hook, each getting
+     * what the one before answered. The first failure stops the chain and
+     * travels up: a refusal is a refusal, and the caller must not go on as if
+     * the chain had said yes.
+     *
+     * Hooks run outside the request being served: what a hook reads or writes
+     * to validate, complete or keep track of an operation is the server's
+     * (#385). The request is in the arguments of the hooks that judge, which
+     * judge by it; a hook acting as the caller names it.
+     *
+     * @param name the hook
+     * @param value the value to thread
+     * @returns the last value in the chain
+     */
+    chain<K extends keyof Hooks>(name: ChainedNameOf<K>, value: ChainedValue<K>): Promise<ChainedValue<K>>;
+    /**
+     * Notify every subscriber of a hook, one after the other, outside the
+     * request that caused it: they are told what happened, and was judged, and
+     * react as the server — synchronizing, publishing, keeping invariants —
+     * whoever asked.
+     *
+     * Not awaited, and not failed: the write the subscribers react to is done,
+     * and a subscriber's failure is logged and goes no further. `settled`
+     * waits for them.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     */
+    notify<K extends NotifiedName>(name: K, ...args: Args<K>): void;
+    /**
+     * Run every subscriber of a hook and let their failures go to the caller,
+     * for the rare hook whose subscribers are part of the answer: a logout
+     * token reaches the provider only once what it closes is recorded, so the
+     * failure has to reach the library, which answers 400 and lets the
+     * provider retry.
+     *
+     * Every subscriber runs even when one fails, one after the other as
+     * `notify` runs them, and the first failure is raised once they all have:
+     * stopping at the first would cost the others their turn — a session the
+     * provider considers closed would keep working against the store that
+     * would have killed it.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     */
+    notifyStrict<K extends NotifiedName>(name: K, ...args: Args<K>): Promise<void>;
+    /**
+     * Notify, then wait for the subscribers: a caller that has to know the
+     * consequences have run, a test instead of a sleep.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     * @returns once they have returned
+     */
+    notifyAndWait<K extends NotifiedName>(name: K, ...args: Args<K>): Promise<void>;
+    /**
+     * Run every hook the server holds and answer what each gives, in order.
+     * For the hooks nothing decided the answer of: `hello` is a demo of one.
+     *
+     * @param name the hook
+     * @param args what its subscribers are given
+     * @returns one answer per subscriber
+     */
+    call<K extends keyof Hooks>(name: K, ...args: Args<K>): Promise<unknown[]>;
+    /**
+     * A view raising `{prefix}{suffix}` hooks, for an entity whose hooks are
+     * named dynamically.
+     *
+     * @param prefix the entity's prefix
+     * @returns the bus, raising its hooks
+     */
+    prefixed(prefix: string): FlatHookBus;
+    /**
+     * Resolves when every notification started so far has run, the ones
+     * started while waiting included.
+     */
+    settled(): Promise<void>;
+    /**
+     * Write a hook's subscribers the way `server.hooks` spells them: no entry
+     * when nothing is subscribed, the function itself for one subscriber.
+     */
+    private store;
+    private fire;
+}
+export {};

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

@@ -1,11 +1,3 @@
-/**
- * @module lib/instanceProviders
- *
- * The two places a workplace instance can be created: the Cloudery, which
- * answers at once and builds the instance afterwards, and the cozy-stack
- * admin API, which builds it before answering.
- */
-import { type RequestInit, type Response } from 'node-fetch';
 /**
  * Reduce a name to what the Cloudery takes in a slug; it refused `_` or `@`
  * with "Slug is invalid". `-` is kept, except at either end where no host

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

@@ -100,6 +100,8 @@ declare class ldapActions {
     private attrSignatureCache;
     private waitingResolvers;
     private availableConnections;
+    /** Connections being opened, not yet in `connectionPool` */
+    private opening;
     private isCleaningUp;
     /** See {@link declareObjectClasses}. */
     private declaredClasses;
@@ -156,9 +158,14 @@ declare class ldapActions {
         busy: number;
         idle: number;
         waiting: number;
+        opening: number;
         max: number;
     };
     private takeConnection;
+    /** Refuse every queued request with `error` */
+    private refuseWaiters;
+    /** Let one queued request take a place that freed with no connection */
+    private wakeWaiter;
     /**
      * Release a connection back to the pool
      * If there are waiting requests, hand off the connection directly
@@ -363,10 +370,12 @@ declare class ldapActions {
      * the directory applies both, and only one would have been judged.
      *
      * Without the schema, the case is still set, and a name given as an OID,
-     * which nothing here could resolve, is refused.
+     * which nothing here could resolve, is refused. So is, with or without
+     * it, a name that is neither a descriptor nor a numeric OID.
      *
      * @param entry attributes of an add, or one part of a modify
-     * @throws BadRequestError on an option, or on one attribute named twice
+     * @throws BadRequestError on an option, on a name that describes no
+     * attribute, or on one attribute named twice
      */
     canonicalAttributes(entry: AttributesList | undefined): Promise<void>;
     /**

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

@@ -17,9 +17,14 @@ export type ConfigEntry = [
 ];
 export declare class ConfigParser {
     private config;
+    /** CLI arguments no entry declared, kept in `Config` by the parser */
+    private unknownArgs;
+    get unknownOptions(): string[];
     constructor(config: ConfigTemplate);
     parse(argv?: string[]): Config;
     private parseCliArgs;
     private getKeyFromCliArg;
 }
+export declare function splitValue(value: string, kind: ArrayKind | undefined, form: 'singular' | 'plural'): string[];
+export declare function parseNumber(value: string): number;
 export declare function parseConfig(config: ConfigEntry[], argv?: string[]): Config;