ldap-rest 0.2.1 → 0.3.0

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;

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

@@ -0,0 +1,23 @@
+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';
+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;
+}

package/dist/src/plugins/twake/drive.d.ts

@@ -83,4 +83,11 @@ export default class Drive extends TwakePlugin {
      * @returns true if successful, false otherwise
      */
     unblockInstance(dn: string): Promise<boolean>;
+    /**
+     * Delete a Cozy instance and all its data
+     * Calls DELETE /instances/:domain on the Cozy Admin API
+     * @param dn User's LDAP DN
+     * @returns true if successful, false otherwise
+     */
+    deleteInstance(dn: string): Promise<boolean>;
 }