ldap-rest 0.6.2 → 0.8.0

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

@@ -1,7 +1,3 @@
-/**
- * LDAP low-level library
- * @author Xavier Guimard <xguimard@linagora.com>
- */
 import type { Request } from 'express';
 import type { ClientOptions, SearchResult, SearchOptions } from 'ldapts';
 import type winston from 'winston';
@@ -12,6 +8,27 @@ export type AttributeValue = Buffer | Buffer[] | string[] | string;
 export type AttributesList = Record<string, AttributeValue>;
 export type LdapList = Record<string, AttributesList>;
 export type { SearchOptions, SearchResult };
+/**
+ * The directory as seen by one HTTP request.
+ *
+ * `ldapActions`'s own methods take the request as a trailing optional
+ * argument, and the authorization plugins hook `ldap*request` and skip every
+ * check when it is missing — so omitting it is an authorization bypass that
+ * fails silently rather than loudly. Three shipped in the SCIM plugin alone.
+ *
+ * These methods take no request parameter: it is captured once by
+ * `ldapActions.forRequest()`, and forgetting it stops being expressible.
+ * Request handlers should bind once and use this; the unbound methods remain
+ * for work that genuinely belongs to no request, such as startup and cron
+ * tasks, where passing nothing is the deliberate answer.
+ */
+export interface RequestBoundLdap {
+    search(options: SearchOptions, base?: string): Promise<SearchResult | AsyncGenerator<SearchResult>>;
+    add(dn: string, entry: AttributesList): Promise<boolean>;
+    modify(dn: string, changes: ModifyRequest): Promise<boolean>;
+    rename(dn: string, newRdn: string): Promise<boolean>;
+    delete(dn: string | string[]): Promise<boolean>;
+}
 export interface ModifyRequest {
     add?: AttributesList;
     replace?: AttributesList;
@@ -26,6 +43,22 @@ declare class ldapActions {
     parent: DM;
     logger: winston.Logger;
     private searchCache;
+    private cacheEnabled;
+    /**
+     * How many writes this instance has made since it was built.
+     *
+     * A read can be overtaken by a write: the write lands and `invalidateCache`
+     * finds nothing to drop, because the read has not stored its answer yet —
+     * and the read then stores what it read *before* the write, an entry
+     * nothing will drop until its TTL runs out. `search()` remembers the count
+     * it started at and stores only if no write happened in between, so a read
+     * a write overtook costs a cache entry, never a stale answer.
+     *
+     * The count is per instance and per write, not per DN: a write to another
+     * branch keeps a concurrent read out of the cache too. That is hit rate
+     * given up, not freshness.
+     */
+    private cacheGeneration;
     queryLimit: ReturnType<typeof pLimit>;
     private connectionPool;
     private poolSize;
@@ -62,13 +95,33 @@ declare class ldapActions {
     private getAttributeSignature;
     /**
      * Generate cache key for LDAP search
+     *
+     * Every option that changes the answer belongs in here, or a search that
+     * asked for more is served what a search that asked for less got: the
+     * requested attributes above all, but also the ones that change the shape
+     * of what comes back. `timeLimit` is deliberately absent — it bounds how
+     * long the server may spend, not what it returns.
      */
     private getCacheKey;
     /**
-     * Invalidate cache entries for a specific DN
-     * Called after modifications to ensure cache consistency
+     * Drop every cached read of `dn`, and of everything below it.
+     *
+     * Called after each write, so the next read of what just changed goes to
+     * the directory. Two things this does that a `key.startsWith(dn)` test did
+     * not: it compares DNs the way the directory does (see {@link foldDn}), so
+     * a write spelling a DN differently from the read that cached it still
+     * drops it; and it drops the subtree, because `rename()` and `move()`
+     * re-parent a whole branch in one operation — renaming an organization
+     * changes the DN of every entry under it — leaving the cached reads of
+     * those children filed under DNs that no longer exist. A leaf has nothing
+     * below it and the extra test costs nothing.
      */
     invalidateCache(dn: string): void;
+    /**
+     * Bind every directory operation to one request, so the authorization
+     * hooks always see it. See {@link RequestBoundLdap}.
+     */
+    forRequest(req: Request): RequestBoundLdap;
     search(options: SearchOptions, base?: string, req?: Request): Promise<SearchResult | AsyncGenerator<SearchResult>>;
     /**
      * Wrap paginated search to ensure connection is released when done

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

@@ -41,6 +41,30 @@ export declare const transformSchemas: (schemas: string | Buffer, config: Config
  * ```
  */
 export declare function escapeLdapFilter(value: string): string;
+/**
+ * Build the LDAP filter of a list search: a substring match on one attribute,
+ * or on any of several.
+ *
+ * The value is escaped, so nothing a client types can reach the filter as
+ * syntax; the attribute names cannot be escaped — they *are* syntax — so they
+ * are checked against what an LDAP attribute name may contain and refused
+ * otherwise.
+ *
+ * Every list route builds the same filter, and a client asking for a mail
+ * address expects the same answer whichever entity it is asking about.
+ *
+ * @param match - The substring to look for
+ * @param attribute - One attribute name, or several separated by commas
+ * @returns The LDAP filter
+ * @throws BadRequestError when an attribute name is not one
+ *
+ * @example
+ * ```typescript
+ * substringSearchFilter('ali', 'cn,mail')
+ * // => '(|(cn=*ali*)(mail=*ali*))'
+ * ```
+ */
+export declare function substringSearchFilter(match: string, attribute: string): string;
 /**
  * Escape special characters in LDAP DN attribute values according to RFC 4514
  * Prevents LDAP injection attacks by escaping characters that have special meaning in DNs
@@ -145,6 +169,22 @@ export declare function getParentDn(dn: string): string;
  * ```
  */
 export declare function getRdn(dn: string): string;
+/**
+ * Extract the *value* of the first RDN of a DN, with its escapes removed
+ *
+ * Where {@link getRdn} returns `ou=Test Org`, this returns `Test Org`: the
+ * name the entry is known by, which is what a path or a label is built from.
+ *
+ * @param dn - The DN to read
+ * @returns The value, or an empty string when the DN has no RDN
+ *
+ * @example
+ * ```typescript
+ * rdnValue('ou=Test\\, Org,ou=organization,dc=example,dc=com')
+ * // => 'Test, Org'
+ * ```
+ */
+export declare function rdnValue(dn: string): string;
 /**
  * Check if a DN is a child of another DN
  *
@@ -184,6 +224,31 @@ export declare function isChildOf(dn: string, parentDn: string): boolean;
  * ```
  */
 export declare function normalizeDn(dn: string): string;
+/**
+ * Whether a member DN is the placeholder a `groupOfNames` holds so it stays
+ * valid with no real member (`--group-dummy-user`).
+ *
+ * Compared as DNs rather than as text: the directory answers with its own
+ * spelling, so the configured `uid=fakeUser,ou=users,…` has to match the
+ * `uid=fakeuser, ou=users,…` a group may actually hold. A textual comparison
+ * counted such a member as a real one — enough to make an empty group refuse
+ * deletion, and to show the placeholder to SCIM clients.
+ *
+ * Every reader of the member list asks here, so the four of them cannot drift
+ * apart again.
+ *
+ * @param member - The member DN to test
+ * @param dummy - The configured placeholder DN, if any
+ * @returns true when `member` is that placeholder; false when none is
+ *          configured, as there is then no placeholder to hide
+ *
+ * @example
+ * ```typescript
+ * isDummyMemberDn('uid=fakeuser, ou=users,dc=e,dc=c', 'uid=fakeUser,ou=users,dc=e,dc=c')
+ * // => true
+ * ```
+ */
+export declare function isDummyMemberDn(member: unknown, dummy: string | undefined): boolean;
 /**
  * Check whether a DN is a branch base itself or sits anywhere below it.
  *

package/dist/src/plugins/auth/authzScope.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module plugins/auth/authzScope
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * Tells a client what the signed-in administrator may actually do, before it
+ * offers them a button that will fail.
+ *
+ * In a local-administration model the scope *is* the interface: a manager
+ * administers a few branches of the tree and nothing else, and an application
+ * that cannot name those branches leaves them guessing. This endpoint answers
+ * both halves — which branches, and which entities can be created in them —
+ * by asking the authorization plugin in force, whichever one that is.
+ * @group Plugins
+ */
+import type { Express } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+export default class AuthzScope extends DmPlugin {
+    name: string;
+    roles: Role[];
+    /**
+     * Register `GET {api_prefix}/v1/authz/scope`.
+     *
+     * @param app Express application
+     */
+    api(app: Express): void;
+    /**
+     * The authorization plugin in force, if any.
+     *
+     * @returns the plugin, or undefined when the server is unrestricted
+     */
+    private authz;
+    /**
+     * Entities a client can create, as declared by the loaded plugins.
+     *
+     * @returns entity name and branch, one per creatable entity
+     */
+    private entities;
+    /**
+     * Answer the scope request.
+     *
+     * @param req Express request, carrying the authenticated user
+     * @param res Express response
+     */
+    private scope;
+    /**
+     * Read the display name and path of a branch, so a client can show the
+     * scope in the words the directory uses rather than as a raw DN.
+     *
+     * @param dn branch to describe
+     * @returns name and path when the entry carries them
+     */
+    private branchLabel;
+}

package/dist/src/plugins/auth/llng.d.ts

@@ -1,8 +1,37 @@
-import type { Response } from 'express';
+/**
+ * @module plugins/auth/llng
+ * @group Plugins
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * Lemonldap::NG authentication plugin
+ * This plugin enables authentication and authorization using Lemonldap::NG.
+ */
+import type { Express, Response } from 'express';
 import AuthBase, { DmRequest } from '../../lib/auth/base';
 import type { Role } from '../../abstract/plugin';
+type LlngHandler = typeof import('lemonldap-ng-handler');
 export default class AuthLLNG extends AuthBase {
     name: string;
     roles: Role[];
+    private handler?;
+    /**
+     * Load the optional `lemonldap-ng-handler` dependency before the server
+     * starts serving requests, rather than importing it statically.
+     *
+     * A static import would throw the moment this file is loaded — as soon as
+     * this plugin is configured — with Node's own opaque "Cannot find
+     * package" error. Loading it here instead means a server that never
+     * configures this plugin never touches the package at all, and one that
+     * does configure it gets a clear failure naming both the plugin and the
+     * missing dependency, at startup, instead of on the first request an auth
+     * plugin that cannot run must not pretend to succeed.
+     */
+    api(app: Express): Promise<void>;
+    /**
+     * Load the handler. Split out so tests can override it to simulate the
+     * dependency being absent, without actually uninstalling it.
+     */
+    protected loadHandler(): Promise<LlngHandler>;
     authMethod(req: DmRequest, res: Response, next: () => void): void;
 }
+export {};

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

@@ -0,0 +1,56 @@
+import type { Express } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+/**
+ * Draw a password from {@link PASSWORD_ALPHABET} with a uniform distribution.
+ *
+ * Bytes whose value would wrap the alphabet are discarded rather than folded
+ * with a modulo, which would make the first characters of the alphabet more
+ * likely than the last.
+ *
+ * @param length number of characters
+ * @returns the generated password
+ */
+export declare function generatePassword(length?: number): string;
+export default class LdapAccountLifecycle extends DmPlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        ldapFlatGeneric: string;
+    };
+    /**
+     * Register the lifecycle endpoints of every flat entity whose schema asks
+     * for them.
+     *
+     * @param app Express application
+     */
+    api(app: Express): void;
+    /**
+     * Apply a named state to an account.
+     *
+     * @param entity flat entity holding the account
+     * @param attribute attribute carrying the state
+     * @param states state names declared by the schema
+     * @param req Express request
+     * @param res Express response
+     */
+    private setStatus;
+    /**
+     * Replace an account's credential, and flag it for a change at next login
+     * when the schema knows how to.
+     *
+     * @param entity flat entity holding the account
+     * @param attribute attribute carrying the credential
+     * @param req Express request
+     * @param res Express response
+     */
+    private resetPassword;
+    /**
+     * Apply a change through the entity's own modify path, turning a missing
+     * entry into a 404 rather than a directory error.
+     *
+     * @param entity flat entity holding the account
+     * @param id identifier or DN of the entry
+     * @param changes modification to apply
+     */
+    private modify;
+}

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

@@ -15,7 +15,50 @@ export default class LdapDepartmentSync extends DmPlugin {
     private linkAttr;
     private pathAttr;
     constructor(server: DM);
+    /**
+     * The attribute holding an organization's path: the `organizationPath` role
+     * of the organization schema, then the configured name.
+     *
+     * Role first, as the enterprise rules read it: a deployment naming the
+     * attribute only through the role otherwise saw nothing recomputed, and
+     * nothing said so. Resolved on each call, the organization schema being
+     * read asynchronously.
+     *
+     * @returns the attribute name
+     */
+    private organizationPathAttribute;
+    /**
+     * The link and path attributes of the entries attached to an organization:
+     * those every loaded entity schema declares through the `organizationLink`
+     * and `organizationPath` roles, then the configured names.
+     *
+     * @returns distinct pairs, the ones declared by roles first
+     */
+    private linkedAttributes;
     hooks: Hooks;
+    /**
+     * Recompute the path of a renamed or moved organization and of every
+     * organization below it.
+     *
+     * A path names an organization's ancestors, root first, its own name last,
+     * the top organization left out. Moving or renaming one therefore changes
+     * the path of its whole subtree. Only the entries *linked* to the tree used
+     * to be updated, from paths the tree itself still held: the organizations
+     * kept the path of their former parent, the linked users were rewritten to
+     * it, and nothing could correct it since the path is computed by the server.
+     *
+     * Only organizations already holding a path are written.
+     *
+     * @param orgDn DN of the organization after the rename
+     */
+    private updateOrganizationPaths;
+    /**
+     * Read the path an organization holds.
+     *
+     * @param dn organization DN
+     * @returns its path, or null when it holds none or cannot be read
+     */
+    private readPath;
     /**
      * Update resources that are directly linked to the renamed organization
      */