ldap-rest 0.2.2 → 0.3.1

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

@@ -0,0 +1,412 @@
+import type { Express } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type ldapActions from '../../lib/ldapActions';
+import { writeScimErrorFromException } from './errors';
+/**
+ * Reusable SCIM 2.0 schemas surfaced by this plugin.
+ * Picked up by scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * ScimUser:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 User resource (RFC 7643 §4.1).
+ *   required: [schemas, userName]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:User']
+ *     id:
+ *       type: string
+ *       description: Opaque server-assigned identifier.
+ *       example: 2819c223-7f76-453a-919d-413861904646
+ *     externalId:
+ *       type: string
+ *       description: Provisioner-assigned identifier.
+ *       example: 701984
+ *     userName:
+ *       type: string
+ *       description: Unique user identifier (login name).
+ *       example: bjensen
+ *     name:
+ *       type: object
+ *       properties:
+ *         formatted: { type: string, example: Ms. Barbara J Jensen III }
+ *         familyName: { type: string, example: Jensen }
+ *         givenName: { type: string, example: Barbara }
+ *         middleName: { type: string, example: Jane }
+ *         honorificPrefix: { type: string, example: Ms. }
+ *         honorificSuffix: { type: string, example: III }
+ *     displayName:
+ *       type: string
+ *       example: Babs Jensen
+ *     nickName:
+ *       type: string
+ *       example: Babs
+ *     profileUrl:
+ *       type: string
+ *       example: https://login.example.com/bjensen
+ *     title:
+ *       type: string
+ *       example: Tour Guide
+ *     userType:
+ *       type: string
+ *       example: Employee
+ *     preferredLanguage:
+ *       type: string
+ *       example: en-US
+ *     locale:
+ *       type: string
+ *       example: en-US
+ *     timezone:
+ *       type: string
+ *       example: America/Los_Angeles
+ *     active:
+ *       type: boolean
+ *       example: true
+ *     emails:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string }
+ *           display: { type: string }
+ *           type: { type: string }
+ *           primary: { type: boolean }
+ *       example:
+ *         - value: bjensen@example.com
+ *           type: work
+ *           primary: true
+ *     phoneNumbers:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string }
+ *           type: { type: string }
+ *           primary: { type: boolean }
+ *     addresses:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           streetAddress: { type: string }
+ *           locality: { type: string }
+ *           region: { type: string }
+ *           postalCode: { type: string }
+ *           country: { type: string }
+ *           type: { type: string }
+ *           primary: { type: boolean }
+ *     groups:
+ *       type: array
+ *       description: Groups the user belongs to (read-only).
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string }
+ *           $ref: { type: string }
+ *           display: { type: string }
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: User }
+ *         created: { type: string, format: date-time }
+ *         lastModified: { type: string, format: date-time }
+ *         location: { type: string }
+ *         version: { type: string }
+ * ScimGroup:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 Group resource (RFC 7643 §4.2).
+ *   required: [schemas, displayName]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:Group']
+ *     id:
+ *       type: string
+ *       description: Opaque server-assigned identifier.
+ *       example: e9e30dba-f08f-4109-8486-d5c6a331660a
+ *     externalId:
+ *       type: string
+ *       example: 00g1emaKYZTWRINFRGETl
+ *     displayName:
+ *       type: string
+ *       example: Tour Guides
+ *     members:
+ *       type: array
+ *       description: Members of the group.
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string, description: User or Group id }
+ *           $ref: { type: string }
+ *           display: { type: string }
+ *       example:
+ *         - value: 2819c223-7f76-453a-919d-413861904646
+ *           display: Babs Jensen
+ *         - value: 902c246b-6245-4190-8e05-00816be7344a
+ *           display: Mandy Pepperidge
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: Group }
+ *         created: { type: string, format: date-time }
+ *         lastModified: { type: string, format: date-time }
+ *         location: { type: string }
+ *         version: { type: string }
+ * ScimListResponse:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 list query response (urn:ietf:params:scim:api:messages:2.0:ListResponse).
+ *   required: [schemas, totalResults, Resources]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:ListResponse']
+ *     totalResults:
+ *       type: integer
+ *       description: Total number of matching resources.
+ *       example: 2
+ *     startIndex:
+ *       type: integer
+ *       description: 1-based index of the first result returned.
+ *       example: 1
+ *     itemsPerPage:
+ *       type: integer
+ *       description: Number of resources returned in this page.
+ *       example: 2
+ *     Resources:
+ *       type: array
+ *       items: {}
+ *       description: The matching resources.
+ * ScimError:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 error response (urn:ietf:params:scim:api:messages:2.0:Error).
+ *   required: [schemas, status]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:Error']
+ *     status:
+ *       type: string
+ *       description: HTTP status code as a string.
+ *       example: '404'
+ *     scimType:
+ *       type: string
+ *       description: |
+ *         SCIM error type keyword (RFC 7644 §3.12). One of: invalidFilter,
+ *         tooMany, uniqueness, mutability, invalidSyntax, invalidPath,
+ *         noTarget, invalidValue, invalidVers, sensitive.
+ *       example: mutability
+ *     detail:
+ *       type: string
+ *       description: Human-readable error description.
+ *       example: Resource 2819c223-7f76-453a-919d-413861904646 not found.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:Error']
+ *     status: '404'
+ *     detail: Resource 2819c223-7f76-453a-919d-413861904646 not found.
+ * ScimPatchOp:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 patch request body (urn:ietf:params:scim:api:messages:2.0:PatchOp,
+ *     RFC 7644 §3.5.2).
+ *   required: [schemas, Operations]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:PatchOp']
+ *     Operations:
+ *       type: array
+ *       items:
+ *         type: object
+ *         required: [op]
+ *         properties:
+ *           op:
+ *             type: string
+ *             enum: [add, remove, replace, Add, Remove, Replace]
+ *           path:
+ *             type: string
+ *             description: SCIM attribute path (e.g. "emails[type eq \"work\"].value").
+ *           value:
+ *             description: New value for the target attribute.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:PatchOp']
+ *     Operations:
+ *       - op: replace
+ *         path: active
+ *         value: false
+ *       - op: replace
+ *         path: emails[type eq "work"].value
+ *         value: bjensen@newdomain.example.com
+ * ScimBulkRequest:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 Bulk request (urn:ietf:params:scim:api:messages:2.0:BulkRequest,
+ *     RFC 7644 §3.7).
+ *   required: [schemas, Operations]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:BulkRequest']
+ *     failOnErrors:
+ *       type: integer
+ *       description: |
+ *         Stop processing after this many errors. Omit or set to 0 to
+ *         continue on errors and process all operations.
+ *       example: 1
+ *     Operations:
+ *       type: array
+ *       items:
+ *         type: object
+ *         required: [method, path]
+ *         properties:
+ *           method:
+ *             type: string
+ *             enum: [POST, PUT, PATCH, DELETE]
+ *           bulkId:
+ *             type: string
+ *             description: |
+ *               Temporary client-assigned identifier for this operation.
+ *               Subsequent operations in the same request may reference the
+ *               created resource as "bulkId:<value>".
+ *           path:
+ *             type: string
+ *             description: Resource path relative to the SCIM prefix (e.g. /Users or /Groups/123).
+ *           data:
+ *             description: Request body for POST/PUT/PATCH operations.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:BulkRequest']
+ *     failOnErrors: 1
+ *     Operations:
+ *       - method: POST
+ *         bulkId: qwerty
+ *         path: /Users
+ *         data:
+ *           schemas: ['urn:ietf:params:scim:schemas:core:2.0:User']
+ *           userName: bjensen
+ *           name:
+ *             familyName: Jensen
+ *             givenName: Barbara
+ *       - method: DELETE
+ *         path: /Users/2819c223-7f76-453a-919d-413861904646
+ * ScimBulkResponse:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 Bulk response (urn:ietf:params:scim:api:messages:2.0:BulkResponse).
+ *   required: [schemas, Operations]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:BulkResponse']
+ *     Operations:
+ *       type: array
+ *       items:
+ *         type: object
+ *         required: [method, status]
+ *         properties:
+ *           method:
+ *             type: string
+ *             enum: [POST, PUT, PATCH, DELETE]
+ *           bulkId:
+ *             type: string
+ *           location:
+ *             type: string
+ *             description: URL of the created/modified resource.
+ *           version:
+ *             type: string
+ *           status:
+ *             type: string
+ *             description: HTTP status code for this individual operation.
+ *           response:
+ *             $ref: '#/components/schemas/ScimError'
+ *             description: Present only when the operation failed.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:BulkResponse']
+ *     Operations:
+ *       - method: POST
+ *         bulkId: qwerty
+ *         location: https://example.com/scim/v2/Users/2819c223-7f76-453a-919d-413861904646
+ *         status: '201'
+ *       - method: DELETE
+ *         status: '204'
+ * ScimResourceType:
+ *   type: object
+ *   description: SCIM 2.0 ResourceType definition (RFC 7643 §6).
+ *   required: [schemas, id, name, endpoint, schema]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:ResourceType']
+ *     id: { type: string, example: User }
+ *     name: { type: string, example: User }
+ *     endpoint: { type: string, example: /Users }
+ *     description: { type: string, example: User Account }
+ *     schema:
+ *       type: string
+ *       example: urn:ietf:params:scim:schemas:core:2.0:User
+ *     schemaExtensions:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           schema: { type: string }
+ *           required: { type: boolean }
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: ResourceType }
+ *         location: { type: string }
+ * ScimSchema:
+ *   type: object
+ *   description: SCIM 2.0 Schema definition (RFC 7643 §7).
+ *   required: [schemas, id, name, attributes]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:Schema']
+ *     id:
+ *       type: string
+ *       example: urn:ietf:params:scim:schemas:core:2.0:User
+ *     name: { type: string, example: User }
+ *     description: { type: string, example: User Account }
+ *     attributes:
+ *       type: array
+ *       items: {}
+ *       description: Schema attribute definitions.
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: Schema }
+ *         location: { type: string }
+ */
+export default class Scim extends DmPlugin {
+    name: string;
+    roles: Role[];
+    ldap: ldapActions;
+    private readonly scimPrefix;
+    private readonly users;
+    private readonly groups;
+    private readonly bulk;
+    private readonly discovery;
+    private readonly baseResolver;
+    constructor(server: DM);
+    private scimJson;
+    private readScimBody;
+    api(app: Express): void;
+    private parseListQuery;
+    getConfigApiData(): Record<string, unknown>;
+}
+export { writeScimErrorFromException };

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

@@ -0,0 +1,222 @@
+/**
+ * @module plugins/scim/types
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * SCIM 2.0 type definitions (RFC 7643 / RFC 7644).
+ */
+export declare const SCHEMA_USER = "urn:ietf:params:scim:schemas:core:2.0:User";
+export declare const SCHEMA_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group";
+export declare const SCHEMA_LIST_RESPONSE = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+export declare const SCHEMA_ERROR = "urn:ietf:params:scim:api:messages:2.0:Error";
+export declare const SCHEMA_PATCH_OP = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
+export declare const SCHEMA_BULK_REQUEST = "urn:ietf:params:scim:api:messages:2.0:BulkRequest";
+export declare const SCHEMA_BULK_RESPONSE = "urn:ietf:params:scim:api:messages:2.0:BulkResponse";
+export declare const SCHEMA_SERVICE_PROVIDER_CONFIG = "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig";
+export declare const SCHEMA_RESOURCE_TYPE = "urn:ietf:params:scim:schemas:core:2.0:ResourceType";
+export declare const SCHEMA_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Schema";
+export interface Meta {
+    resourceType: 'User' | 'Group';
+    created?: string;
+    lastModified?: string;
+    location?: string;
+    version?: string;
+}
+export interface MultiValued<T extends string = string> {
+    value: T;
+    display?: string;
+    type?: string;
+    primary?: boolean;
+    $ref?: string;
+}
+export interface ScimName {
+    formatted?: string;
+    familyName?: string;
+    givenName?: string;
+    middleName?: string;
+    honorificPrefix?: string;
+    honorificSuffix?: string;
+}
+export interface ScimUser {
+    schemas: string[];
+    id?: string;
+    externalId?: string;
+    userName?: string;
+    name?: ScimName;
+    displayName?: string;
+    nickName?: string;
+    profileUrl?: string;
+    title?: string;
+    userType?: string;
+    preferredLanguage?: string;
+    locale?: string;
+    timezone?: string;
+    active?: boolean;
+    password?: string;
+    emails?: MultiValued[];
+    phoneNumbers?: MultiValued[];
+    ims?: MultiValued[];
+    photos?: MultiValued[];
+    addresses?: ScimAddress[];
+    groups?: MultiValued[];
+    entitlements?: MultiValued[];
+    roles?: MultiValued[];
+    x509Certificates?: MultiValued[];
+    meta?: Meta;
+    [ext: string]: unknown;
+}
+export interface ScimAddress {
+    formatted?: string;
+    streetAddress?: string;
+    locality?: string;
+    region?: string;
+    postalCode?: string;
+    country?: string;
+    type?: string;
+    primary?: boolean;
+}
+export interface ScimGroup {
+    schemas: string[];
+    id?: string;
+    externalId?: string;
+    displayName?: string;
+    members?: MultiValued[];
+    meta?: Meta;
+    [ext: string]: unknown;
+}
+export type ScimResource = ScimUser | ScimGroup;
+export interface ListResponse<T> {
+    schemas: [typeof SCHEMA_LIST_RESPONSE];
+    totalResults: number;
+    startIndex: number;
+    itemsPerPage: number;
+    Resources: T[];
+}
+export type ScimErrorType = 'invalidFilter' | 'tooMany' | 'uniqueness' | 'mutability' | 'invalidSyntax' | 'invalidPath' | 'noTarget' | 'invalidValue' | 'invalidVers' | 'sensitive';
+export interface ScimErrorResponse {
+    schemas: [typeof SCHEMA_ERROR];
+    status: string;
+    scimType?: ScimErrorType;
+    detail?: string;
+}
+export interface PatchOperation {
+    op: 'add' | 'remove' | 'replace' | 'Add' | 'Remove' | 'Replace';
+    path?: string;
+    value?: unknown;
+}
+export interface PatchRequest {
+    schemas: string[];
+    Operations: PatchOperation[];
+}
+export interface BulkOperationRequest {
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    bulkId?: string;
+    version?: string;
+    path: string;
+    data?: unknown;
+}
+export interface BulkRequest {
+    schemas: string[];
+    failOnErrors?: number;
+    Operations: BulkOperationRequest[];
+}
+export interface BulkOperationResponse {
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    bulkId?: string;
+    version?: string;
+    location?: string;
+    status: string;
+    response?: ScimErrorResponse;
+}
+export interface BulkResponse {
+    schemas: [typeof SCHEMA_BULK_RESPONSE];
+    Operations: BulkOperationResponse[];
+}
+/**
+ * Internal mapping description: SCIM attribute → LDAP attribute(s).
+ *
+ * - ldap: one LDAP attribute name (simple mapping)
+ * - ldapPrimary/ldapSecondary: primary vs non-primary in multi-valued attr (emails)
+ * - sub: nested SCIM attribute name (for name.familyName etc.)
+ * - multi: 'single' or 'array' (hint for formatting)
+ * - operational: read-only from LDAP operational attribute
+ */
+export interface MappingEntry {
+    scim: string;
+    ldap?: string;
+    ldapPrimary?: string;
+    ldapSecondary?: string;
+    sub?: Record<string, string>;
+    multi?: 'single' | 'array';
+    readOnly?: boolean;
+    operational?: boolean;
+    converter?: 'boolean' | 'number' | 'string';
+}
+export interface ResourceMapping {
+    resourceType: 'User' | 'Group';
+    schemas: string[];
+    entries: MappingEntry[];
+}
+export interface ServiceProviderConfig {
+    schemas: [typeof SCHEMA_SERVICE_PROVIDER_CONFIG];
+    documentationUri?: string;
+    patch: {
+        supported: boolean;
+    };
+    bulk: {
+        supported: boolean;
+        maxOperations: number;
+        maxPayloadSize: number;
+    };
+    filter: {
+        supported: boolean;
+        maxResults: number;
+    };
+    changePassword: {
+        supported: boolean;
+    };
+    sort: {
+        supported: boolean;
+    };
+    etag: {
+        supported: boolean;
+    };
+    authenticationSchemes: Array<{
+        name: string;
+        description: string;
+        specUri?: string;
+        documentationUri?: string;
+        type: string;
+        primary?: boolean;
+    }>;
+    meta?: {
+        resourceType: 'ServiceProviderConfig';
+        location?: string;
+    };
+}
+export interface ResourceTypeDefinition {
+    schemas: [typeof SCHEMA_RESOURCE_TYPE];
+    id: string;
+    name: string;
+    endpoint: string;
+    description?: string;
+    schema: string;
+    schemaExtensions?: Array<{
+        schema: string;
+        required: boolean;
+    }>;
+    meta?: {
+        resourceType: 'ResourceType';
+        location?: string;
+    };
+}
+export interface SchemaDefinition {
+    schemas: [typeof SCHEMA_SCHEMA];
+    id: string;
+    name: string;
+    description?: string;
+    attributes: unknown[];
+    meta?: {
+        resourceType: 'Schema';
+        location?: string;
+    };
+}

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

@@ -0,0 +1,58 @@
+/**
+ * @module plugins/scim/users
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * SCIM Users 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 ScimUser, type ListResponse, type PatchRequest } from './types';
+export interface ListQuery {
+    filter?: string;
+    startIndex?: number;
+    count?: number;
+    attributes?: string[];
+    excludedAttributes?: string[];
+    sortBy?: string;
+    sortOrder?: 'ascending' | 'descending';
+}
+export interface ScimUsersOptions {
+    ldap: ldapActions;
+    config: Config;
+    logger: winston.Logger;
+    baseResolver: BaseResolver;
+    hooks: {
+        [K: string]: Function[] | undefined;
+    };
+}
+export declare class ScimUsers {
+    private readonly ldap;
+    private readonly config;
+    private readonly logger;
+    private readonly baseResolver;
+    private readonly hooks;
+    private readonly mapping;
+    private readonly rdnAttribute;
+    private readonly objectClass;
+    private readonly idAttribute;
+    private readonly maxResults;
+    private readonly scimPrefix;
+    constructor(opts: ScimUsersOptions);
+    private ctx;
+    private dnForId;
+    get(req: DmRequest, id: string): Promise<ScimUser>;
+    list(req: DmRequest, query: ListQuery): Promise<ListResponse<ScimUser>>;
+    create(req: DmRequest, resource: ScimUser): Promise<ScimUser>;
+    replace(req: DmRequest, id: string, resource: ScimUser): Promise<ScimUser>;
+    patch(req: DmRequest, id: string, patch: PatchRequest): Promise<ScimUser>;
+    delete(req: DmRequest, id: string): Promise<void>;
+    /**
+     * Given a SCIM member value (typically an id), return the LDAP DN.
+     * Used by Groups PATCH and Bulk reference resolution.
+     */
+    resolveRef(req: DmRequest, value: string): Promise<string | undefined>;
+    get userMapping(): ResourceMapping;
+}