ldap-rest 0.2.2 → 0.3.1

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

@@ -11,6 +11,184 @@
  */
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
+/**
+ * Shared OpenAPI schemas surfaced by this plugin. Picked up by
+ * scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * PasswordPolicy:
+ *   type: object
+ *   description: |
+ *     Active OpenLDAP ppolicy configuration. All duration fields are in
+ *     **seconds**. Absent fields mean the policy attribute is not set.
+ *   properties:
+ *     dn:
+ *       type: string
+ *       description: DN of the ppolicy entry.
+ *       example: cn=default,ou=policies,dc=example,dc=com
+ *     pwdMaxAge:
+ *       type: integer
+ *       description: Maximum password age in seconds (0 = never expires).
+ *       example: 7776000
+ *     pwdMinAge:
+ *       type: integer
+ *       description: Minimum password age in seconds before it may be changed.
+ *       example: 0
+ *     pwdInHistory:
+ *       type: integer
+ *       description: Number of previous passwords stored.
+ *       example: 5
+ *     pwdCheckQuality:
+ *       type: integer
+ *       description: Password quality enforcement level (0-2).
+ *       example: 1
+ *     pwdMinLength:
+ *       type: integer
+ *       description: Minimum password length.
+ *       example: 12
+ *     pwdMaxFailure:
+ *       type: integer
+ *       description: Maximum bind failures before lockout.
+ *       example: 5
+ *     pwdLockout:
+ *       type: boolean
+ *       description: Whether account lockout is enabled.
+ *       example: true
+ *     pwdLockoutDuration:
+ *       type: integer
+ *       description: Lockout duration in seconds (0 = permanent until admin reset).
+ *       example: 300
+ *     pwdGraceAuthNLimit:
+ *       type: integer
+ *       description: Number of grace logins allowed after password expires.
+ *       example: 0
+ *     pwdExpireWarning:
+ *       type: integer
+ *       description: Seconds before expiry at which a warning is issued.
+ *       example: 1209600
+ *     pwdMustChange:
+ *       type: boolean
+ *       description: If true, users must change their password after an admin reset.
+ *       example: true
+ *     pwdAllowUserChange:
+ *       type: boolean
+ *       description: Whether users are allowed to change their own password.
+ *       example: true
+ * PasswordStatus:
+ *   type: object
+ *   description: Current password status for a specific user account.
+ *   required: [dn, passwordSet, isExpired, isExpiringSoon, mustChange, isLocked, failureCount, graceLoginsUsed]
+ *   properties:
+ *     dn:
+ *       type: string
+ *       description: Fully-qualified DN of the user.
+ *       example: uid=alice,ou=users,dc=example,dc=com
+ *     passwordSet:
+ *       type: boolean
+ *       description: Whether a userPassword attribute is present.
+ *       example: true
+ *     lastChanged:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       description: ISO-8601 timestamp of last password change, or null if never set.
+ *       example: '2026-01-15T10:00:00.000Z'
+ *     expiresAt:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       description: ISO-8601 expiry timestamp, or null if no max age is configured.
+ *       example: '2026-04-15T10:00:00.000Z'
+ *     daysUntilExpiration:
+ *       type: integer
+ *       nullable: true
+ *       description: Remaining days until expiry (negative means already expired).
+ *       example: 80
+ *     isExpired:
+ *       type: boolean
+ *       example: false
+ *     isExpiringSoon:
+ *       type: boolean
+ *       description: True when expiry is within the configured warning window.
+ *       example: false
+ *     mustChange:
+ *       type: boolean
+ *       description: True when `pwdReset` is set (admin forced change).
+ *       example: false
+ *     isLocked:
+ *       type: boolean
+ *       description: True when the account is currently locked.
+ *       example: false
+ *     lockedAt:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       description: ISO-8601 timestamp of lockout, or null.
+ *       example: null
+ *     failureCount:
+ *       type: integer
+ *       description: Number of recorded bind failures still within the window.
+ *       example: 0
+ *     graceLoginsUsed:
+ *       type: integer
+ *       description: Number of grace logins already consumed.
+ *       example: 0
+ * ExpiringAccount:
+ *   type: object
+ *   description: User whose password is expiring within the warning window.
+ *   required: [dn, expiresAt, daysUntilExpiration]
+ *   properties:
+ *     dn: { type: string, example: uid=bob,ou=users,dc=example,dc=com }
+ *     uid: { type: string, example: bob }
+ *     displayName: { type: string, example: Bob Builder }
+ *     mail: { type: string, example: bob@example.com }
+ *     expiresAt:
+ *       type: string
+ *       format: date-time
+ *       example: '2026-05-01T08:00:00.000Z'
+ *     daysUntilExpiration: { type: integer, example: 6 }
+ * LockedAccount:
+ *   type: object
+ *   description: User account that is currently locked.
+ *   required: [dn, failureCount]
+ *   properties:
+ *     dn: { type: string, example: uid=charlie,ou=users,dc=example,dc=com }
+ *     uid: { type: string, example: charlie }
+ *     displayName: { type: string, example: Charlie Chaplin }
+ *     mail: { type: string, example: charlie@example.com }
+ *     lockedAt:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       example: '2026-04-24T14:30:00.000Z'
+ *     failureCount: { type: integer, example: 5 }
+ * PasswordValidationRequest:
+ *   type: object
+ *   required: [password]
+ *   properties:
+ *     password:
+ *       type: string
+ *       format: password
+ *       description: The candidate password to validate.
+ *       example: 'S3cur3P@ss!'
+ *     dn:
+ *       type: string
+ *       description: Optional user DN for context (not used in local validation).
+ *       example: uid=alice,ou=users,dc=example,dc=com
+ * PasswordValidationResponse:
+ *   type: object
+ *   required: [valid, errors]
+ *   properties:
+ *     valid:
+ *       type: boolean
+ *       description: True when the password meets all complexity rules.
+ *       example: true
+ *     errors:
+ *       type: array
+ *       items: { type: string }
+ *       description: List of failed rule descriptions (empty when valid).
+ *       example: []
+ */
 export default class PasswordPolicy extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -0,0 +1,23 @@
+import type { Config } from '../../config/args';
+import type { DmRequest } from '../../lib/auth/base';
+export interface BaseMapEntry {
+    userBase?: string;
+    groupBase?: string;
+}
+export type BaseMap = Record<string, BaseMapEntry>;
+export declare class BaseResolver {
+    private readonly defaultUserBase;
+    private readonly defaultGroupBase;
+    private readonly userTemplate;
+    private readonly groupTemplate;
+    private readonly map;
+    constructor(config: Config);
+    private applyTemplate;
+    private resolve;
+    userBase(req?: DmRequest | {
+        user?: string;
+    }): string;
+    groupBase(req?: DmRequest | {
+        user?: string;
+    }): string;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * @module plugins/scim/bulk
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * SCIM 2.0 Bulk operations (RFC 7644 §3.7).
+ *
+ * Executes operations sequentially. Supports `bulkId` cross-references:
+ * a POST with `"bulkId":"abc"` creates a resource; subsequent operations
+ * in the same request can reference it as "bulkId:abc" anywhere a SCIM
+ * id or member.value is expected (resolved to the concrete id before
+ * dispatch).
+ */
+import type winston from 'winston';
+import type { Config } from '../../config/args';
+import type { DmRequest } from '../../lib/auth/base';
+import type { ScimUsers } from './users';
+import type { ScimGroups } from './groups';
+import { type BulkRequest, type BulkResponse } from './types';
+import { writeScimErrorFromException } from './errors';
+export interface ScimBulkOptions {
+    config: Config;
+    logger: winston.Logger;
+    users: ScimUsers;
+    groups: ScimGroups;
+    scimPrefix: string;
+    hooks: {
+        [K: string]: Function[] | undefined;
+    };
+}
+export declare class ScimBulk {
+    private readonly config;
+    private readonly logger;
+    private readonly users;
+    private readonly groups;
+    private readonly scimPrefix;
+    private readonly hooks;
+    constructor(opts: ScimBulkOptions);
+    execute(req: DmRequest, body: BulkRequest): Promise<BulkResponse>;
+    private executeOne;
+    private resolveRefs;
+    private buildLocation;
+}
+export { writeScimErrorFromException };

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

@@ -0,0 +1,27 @@
+import type { Config } from '../../config/args';
+import type { DmRequest } from '../../lib/auth/base';
+import { type ResourceTypeDefinition, type ServiceProviderConfig, type SchemaDefinition } from './types';
+export interface DiscoveryOptions {
+    config: Config;
+    schemaDir: string;
+    scimPrefix: string;
+    loadedPlugins: {
+        [name: string]: unknown;
+    };
+}
+export declare class ScimDiscovery {
+    private readonly config;
+    private readonly schemaDir;
+    private readonly scimPrefix;
+    private readonly loadedPlugins;
+    constructor(opts: DiscoveryOptions);
+    private baseUrl;
+    private location;
+    private authSchemes;
+    serviceProviderConfig(req?: DmRequest): ServiceProviderConfig;
+    resourceTypes(req?: DmRequest): ResourceTypeDefinition[];
+    resourceType(name: string, req?: DmRequest): ResourceTypeDefinition | undefined;
+    schemas(req?: DmRequest): SchemaDefinition[];
+    schema(id: string, req?: DmRequest): SchemaDefinition | undefined;
+    private loadSchema;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * @module plugins/scim/errors
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * SCIM 2.0 error envelope (RFC 7644 §3.12) and async handler wrapper.
+ */
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import { HttpError } from '../../lib/errors';
+import { type ScimErrorType } from './types';
+export declare const SCIM_CONTENT_TYPE = "application/scim+json";
+export declare class ScimError extends HttpError {
+    scimType?: ScimErrorType;
+    constructor(status: number, detail: string, scimType?: ScimErrorType);
+}
+export declare const scimInvalidFilter: (detail?: string) => ScimError;
+export declare const scimInvalidPath: (detail?: string) => ScimError;
+export declare const scimInvalidValue: (detail?: string) => ScimError;
+export declare const scimInvalidSyntax: (detail?: string) => ScimError;
+export declare const scimNoTarget: (detail?: string) => ScimError;
+export declare const scimMutability: (detail?: string) => ScimError;
+export declare const scimUniqueness: (detail?: string) => ScimError;
+export declare const scimTooMany: (detail?: string) => ScimError;
+export declare const scimNotFound: (detail?: string) => ScimError;
+export declare function writeScimError(res: Response, status: number, detail: string, scimType?: ScimErrorType): void;
+/**
+ * Extract an LDAP numeric error code from either a thrown ldapts error
+ * (has `.code`) or an Error wrapped by ldapActions (message contains the
+ * original text). Returns undefined if no code is detectable.
+ */
+export declare function extractLdapCode(err: unknown): number | undefined;
+export declare function writeScimErrorFromException(res: Response, err: unknown, fallbackStatus?: number): void;
+/**
+ * Express wrapper that catches errors, serializes them as SCIM
+ * envelope and short-circuits the default Express error middleware.
+ * Accepts both sync and async handlers.
+ */
+export declare const scimAsyncHandler: (fn: (req: Request, res: Response, next: NextFunction) => void | Promise<void>) => RequestHandler;

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

@@ -0,0 +1,13 @@
+import type { ResourceMapping } from './types';
+export interface TranslatedFilter {
+    ldapFilter: string;
+    /** True if the filter contains `id eq "..."`, which the caller should translate into a DN lookup. */
+    touchesId: boolean;
+    /** Extracted id value if the filter is a simple `id eq "..."` (single clause). */
+    idEquals?: string;
+}
+/**
+ * Translate a SCIM filter string into an LDAP filter.
+ * Returns metadata enabling the caller to short-circuit id-equals queries.
+ */
+export declare function scimFilterToLdap(filter: string, mapping: ResourceMapping): TranslatedFilter;

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

@@ -0,0 +1,61 @@
+/**
+ * @module plugins/scim/groups
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * SCIM Groups resource handler — direct access via ldapActions.
+ */
+import type winston from 'winston';
+import type ldapActions from '../../lib/ldapActions';
+import type { Config } from '../../config/args';
+import type { DmRequest } from '../../lib/auth/base';
+import { BaseResolver } from './baseResolver';
+import { type ResourceMapping, type ScimGroup, type ListResponse, type PatchRequest } from './types';
+import type { ScimUsers } from './users';
+export interface GroupListQuery {
+    filter?: string;
+    startIndex?: number;
+    count?: number;
+    sortBy?: string;
+    sortOrder?: 'ascending' | 'descending';
+}
+export interface ScimGroupsOptions {
+    ldap: ldapActions;
+    config: Config;
+    logger: winston.Logger;
+    baseResolver: BaseResolver;
+    users: ScimUsers;
+    hooks: {
+        [K: string]: Function[] | undefined;
+    };
+}
+export declare class ScimGroups {
+    private readonly ldap;
+    private readonly config;
+    private readonly logger;
+    private readonly baseResolver;
+    private readonly users;
+    private readonly hooks;
+    private readonly mapping;
+    private readonly rdnAttribute;
+    private readonly objectClass;
+    private readonly idAttribute;
+    private readonly maxResults;
+    private readonly scimPrefix;
+    constructor(opts: ScimGroupsOptions);
+    private ctx;
+    private dnForId;
+    /**
+     * Resolve an LDAP member DN back to a SCIM reference (for GET responses).
+     * Best-effort: extract the RDN value and a guessed type (User if in user base).
+     */
+    private buildMemberResolver;
+    get(req: DmRequest, id: string): Promise<ScimGroup>;
+    list(req: DmRequest, query: GroupListQuery): Promise<ListResponse<ScimGroup>>;
+    create(req: DmRequest, resource: ScimGroup): Promise<ScimGroup>;
+    replace(req: DmRequest, id: string, resource: ScimGroup): Promise<ScimGroup>;
+    patch(req: DmRequest, id: string, patch: PatchRequest): Promise<ScimGroup>;
+    delete(req: DmRequest, id: string): Promise<void>;
+    /** Used internally and by Bulk to resolve a Group SCIM reference to a DN. */
+    resolveRef(req: DmRequest, value: string): Promise<string | undefined>;
+    get groupMapping(): ResourceMapping;
+}

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

@@ -0,0 +1,52 @@
+import type { AttributesList } from '../../lib/ldapActions';
+import { type ScimUser, type ScimGroup, type ResourceMapping, type MultiValued } from './types';
+export declare const DEFAULT_USER_MAPPING: ResourceMapping;
+export declare const DEFAULT_GROUP_MAPPING: ResourceMapping;
+export declare function loadMappingFile(path: string): ResourceMapping | undefined;
+/**
+ * Build the mapping used at runtime by merging a user-supplied JSON
+ * override on top of the default. Override entries replace default
+ * entries with the same `scim` key; new entries are appended.
+ */
+export declare function mergeMapping(base: ResourceMapping, override?: ResourceMapping): ResourceMapping;
+export interface MappingContext {
+    /** 'rdn' (default), 'entryUUID', or any LDAP attribute name */
+    idAttribute: string;
+    rdnAttribute: string;
+    resourceType: 'User' | 'Group';
+    baseUrl?: string;
+    scimPrefix: string;
+}
+/** Resolve the SCIM id for an LDAP entry, per configuration. */
+export declare function resolveScimId(entry: AttributesList, ctx: MappingContext): string | undefined;
+export declare function buildLocation(id: string, ctx: MappingContext): string | undefined;
+export declare function ldapToScimUser(entry: AttributesList, mapping: ResourceMapping, ctx: MappingContext): ScimUser;
+/**
+ * Convert SCIM User body → LDAP attributes list.
+ * The RDN attribute is set from `userName` (or explicit `id`).
+ * Returns { rdn, attributes } so the caller can build the DN.
+ */
+export declare function scimUserToLdap(user: ScimUser, mapping: ResourceMapping, ctx: MappingContext, objectClass: string[]): {
+    rdn: string;
+    attributes: AttributesList;
+};
+export declare function ldapToScimGroup(entry: AttributesList, mapping: ResourceMapping, ctx: MappingContext, memberResolver?: (dn: string) => MultiValued | undefined): ScimGroup;
+/**
+ * Convert SCIM Group → LDAP attributes (members excluded; they're
+ * resolved separately to DNs by the handler).
+ */
+export declare function scimGroupToLdap(group: ScimGroup, mapping: ResourceMapping, objectClass: string[]): {
+    rdn: string;
+    attributes: AttributesList;
+};
+/**
+ * List of LDAP attributes to request from the directory so all
+ * mapped SCIM attributes can be populated.
+ */
+export declare function requiredLdapAttributes(mapping: ResourceMapping): string[];
+/**
+ * Given a SCIM attribute path like "emails.value" or "name.familyName",
+ * return the corresponding LDAP attribute name (used by filter parser).
+ * Returns undefined if the path is not mapped.
+ */
+export declare function scimPathToLdapAttribute(path: string, mapping: ResourceMapping): string | undefined;

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

@@ -0,0 +1,39 @@
+/**
+ * @module plugins/scim/patch
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * SCIM PatchOp applicator (RFC 7644 §3.5.2) → ldapts ModifyRequest.
+ *
+ * Supports:
+ *  - op: add / remove / replace
+ *  - simple paths:  "displayName", "userName"
+ *  - sub-attribute paths: "name.familyName"
+ *  - multi-valued paths: "emails"
+ *  - Group member ops via filtered path: `members[value eq "alice"]`
+ *  - implicit path (op.value is an object)
+ *
+ * Complex filtered paths on multi-valued attributes OTHER than `members`
+ * (e.g. `emails[type eq "work"]`) are rejected with `invalidPath`: the
+ * plugin only knows how to map them for member-type resolution. Filtered
+ * member operations for Groups are handled via the caller-provided
+ * `resolveMemberRef` hook (SCIM id → LDAP DN lookup).
+ */
+import type { ModifyRequest } from '../../lib/ldapActions';
+import { type ResourceMapping, type PatchRequest } from './types';
+export interface PatchContext {
+    mapping: ResourceMapping;
+    /** For Groups: resolve SCIM member value (id or $ref) → LDAP DN. Async. */
+    resolveMemberRef?: (value: string) => Promise<string | undefined>;
+    /** The LDAP attribute holding members, default 'member'. */
+    memberAttribute?: string;
+}
+export declare function patchToModifyRequest(patch: PatchRequest, ctx: PatchContext): Promise<ModifyRequest>;
+/**
+ * Apply PATCH to a SCIM resource object in-memory (used for PUT-equivalent
+ * or when the resource handler prefers object-level manipulation before
+ * falling back to full replace).
+ *
+ * Returns the mutated resource. Used by tests; the main production path
+ * is patchToModifyRequest() → ldap.modify().
+ */
+export declare function applyPatchToResource<T extends Record<string, unknown>>(resource: T, patch: PatchRequest): T;