ldap-rest 0.2.2 → 0.3.1

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

@@ -0,0 +1,117 @@
+/**
+ * @module plugins/auth/authzDynamic
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * LDAP-backed authentication + per-branch authorization plugin.
+ *
+ * Tokens are stored as entries under a dedicated LDAP branch (one entry per
+ * bearer token). The plugin caches them and enforces read / write / delete
+ * permissions on subsequent LDAP operations — so each client is scoped to
+ * its own subtree without touching the process configuration.
+ *
+ * Entry shape (conventions, overridable via CLI):
+ *   dn: cn=<token-name>,<authz-dynamic-base>
+ *   cn: <token-name>
+ *   userPassword: {SSHA}…             ← secret, hashed
+ *   description: {"tenant":"acme",     ← JSON config
+ *                "bases":[
+ *                  {"dn":"ou=users,ou=acme,dc=example,dc=com",
+ *                   "read":true,"write":true,"delete":true}
+ *                ]}
+ *
+ * The entry is treated as "token for tenant `acme`, permitted to read/write/
+ * delete under `ou=users,ou=acme,…`". Multiple bases per token are allowed.
+ * Sub-branch matching is used (a permission on `ou=acme` covers
+ * `ou=users,ou=acme`).
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+import type { Express, Response } from 'express';
+import { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import AuthBase, { type DmRequest } from '../../lib/auth/base';
+import type { Hooks } from '../../hooks';
+export interface BranchAcl {
+    dn: string;
+    read?: boolean;
+    write?: boolean;
+    delete?: boolean;
+}
+export interface TokenConfig {
+    tenant?: string;
+    bases?: BranchAcl[];
+}
+export interface TokenEntry {
+    dn: string;
+    cn: string;
+    tenant: string;
+    hash: string;
+    bases: BranchAcl[];
+}
+/** Extends DmRequest with the resolved token entry for downstream hooks. */
+export interface AuthzDynamicRequest extends DmRequest {
+    authzToken?: TokenEntry;
+}
+/**
+ * Per-request async context holding the authenticated token.
+ *
+ * Core plugins (ldapGroups, ldapFlat, etc.) do not always forward the Express
+ * `req` object down to `ldapActions.search()` / `.modify()`. Relying solely
+ * on `req` would therefore let un-tracked operations bypass authorization.
+ * Using AsyncLocalStorage gives us a request-scoped, ambient handle that the
+ * authz hooks can read regardless of whether the caller threaded `req`.
+ */
+export declare const authzContext: AsyncLocalStorage<TokenEntry>;
+export default class AuthzDynamic extends AuthBase {
+    name: string;
+    roles: Role[];
+    private tokens;
+    private lastLoad;
+    private lastFailure;
+    private readonly cacheTtlMs;
+    private readonly failureBackoffMs;
+    private readonly base;
+    private readonly tokenAttr;
+    private readonly configAttr;
+    private readonly tenantAttr;
+    private readonly reloadEndpoint;
+    private loading?;
+    constructor(server: DM);
+    api(app: Express): void;
+    /**
+     * Load token entries from LDAP. Swallows errors so a transient LDAP hiccup
+     * does not poison the cache — the previous snapshot stays in use.
+     */
+    reload(): Promise<void>;
+    /**
+     * Ensure the cache is fresh (blocks if reloading).
+     *
+     * On a bootstrap or successful reload the cache is valid for
+     * `cacheTtlMs`. If the load fails, we still refuse to retry on every
+     * request — `failureBackoffMs` (default 1/4 of TTL, min 5 s) keeps the
+     * previous snapshot in use and shields LDAP from a thundering-herd
+     * during an outage.
+     */
+    private ensureFresh;
+    authMethod(req: DmRequest, res: Response, next: () => void): void;
+    /**
+     * Authorization hooks. These run after the auth middleware has populated
+     * `req.authzToken`, so we can read the allowed bases directly from the
+     * request.
+     */
+    hooks: Hooks;
+    /** Read the active token from the async context, or (as a fallback) from `req`. */
+    private activeToken;
+    /**
+     * Throw a ForbiddenError (403) if the token cannot perform `permission` on
+     * the branch containing `branchOrDn`. Any ACL entry that is `branchOrDn`
+     * itself or a parent of it (sub-branch match) qualifies.
+     *
+     * The client-facing message omits the target DN to avoid leaking tenant
+     * topology through authorization failures; the full context is still
+     * logged server-side at debug level for operators.
+     */
+    private requireBranchPermission;
+    /** Expose current cache (primarily for the configApi auto-discovery). */
+    getConfigApiData(): Record<string, unknown>;
+    _tokens(): TokenEntry[];
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Verify a provided bearer token against a stored LDAP-style hash.
+ *
+ * The stored hash is typically the contents of `userPassword`:
+ * either `{SCHEME}<data>` or cleartext.
+ */
+export declare function verifyLdapPassword(provided: string, stored: string): boolean;
+/**
+ * Convenience helpers for tests / tooling to generate an LDAP-style hash.
+ *
+ * These are NOT used by the runtime verification path and NOT intended for
+ * use as a general password-hashing function: the primary use case is
+ * seeding LDAP token fixtures in tests. Production `userPassword` values
+ * should be generated by `slappasswd` (or another operator tool) with a
+ * scheme of your choice. The RFC 3112 `{SSHA}` scheme uses a single SHA-1
+ * round — adequate for LDAP bearer-token interop, not adequate for
+ * user-chosen passwords. Prefer `sshaHash('sha512', …)` (`{SSHA512}`) when
+ * generating new fixtures.
+ */
+export type SshaAlgo = 'sha1' | 'sha256' | 'sha512';
+export declare function sshaHash(algo: SshaAlgo, password: string, salt?: Buffer): string;
+/**
+ * Legacy alias: generate an {SSHA} (salted SHA-1) hash.
+ * Retained so existing tests keep working. Prefer `sshaHash('sha512', ...)`
+ * for new fixtures.
+ */
+export declare function ssha(password: string, salt?: Buffer): string;

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

@@ -10,6 +10,57 @@
  */
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../abstract/plugin';
+/**
+ * @openapi-component
+ * Config:
+ *   type: object
+ *   description: |
+ *     Aggregated server configuration. The top-level fields are always
+ *     present; `features` is a dynamic map whose keys are the names of
+ *     loaded plugins that declare the `configurable` role.  Each plugin
+ *     contributes an arbitrary sub-object — consult the individual plugin
+ *     documentation for its exact shape.
+ *   additionalProperties: true
+ *   properties:
+ *     apiPrefix:
+ *       type: string
+ *       description: The API base path configured on this server.
+ *       example: /api
+ *     ldapBase:
+ *       type: string
+ *       description: The root LDAP suffix used by this server.
+ *       example: dc=example,dc=com
+ *     features:
+ *       type: object
+ *       description: |
+ *         Per-plugin configuration blocks.  Keys match the plugin's
+ *         `name` field; values are plugin-specific objects.
+ *       additionalProperties: true
+ *       example:
+ *         ldapGroups:
+ *           enabled: true
+ *           base: ou=groups,dc=example,dc=com
+ *           mainAttribute: cn
+ *           objectClass: [top, groupOfNames]
+ *         static:
+ *           enabled: true
+ *           staticPath: /static
+ *         appAccountsApi:
+ *           enabled: true
+ *           base: ou=app-accounts,dc=example,dc=com
+ *           maxAccounts: 5
+ *   example:
+ *     apiPrefix: /api
+ *     ldapBase: dc=example,dc=com
+ *     features:
+ *       ldapGroups:
+ *         enabled: true
+ *         base: ou=groups,dc=example,dc=com
+ *         mainAttribute: cn
+ *       static:
+ *         enabled: true
+ *         staticPath: /static
+ */
 export default class ConfigApi extends DmPlugin {
     name: string;
     roles: Role[];

package/dist/src/plugins/demo/helloworld.d.ts

@@ -5,6 +5,27 @@
  */
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
+/**
+ * @openapi-component
+ * Hello:
+ *   type: object
+ *   description: Response returned by the hello-world demo endpoint.
+ *   properties:
+ *     message:
+ *       type: string
+ *       description: Static greeting string.
+ *       example: Hello
+ *     hookResults:
+ *       type: array
+ *       description: |
+ *         Results collected from every function registered on the `hello`
+ *         hook.  Empty when no hook listeners are installed.
+ *       items: {}
+ *       example: []
+ *   example:
+ *     message: Hello
+ *     hookResults: []
+ */
 export default class HelloWorld extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -6,6 +6,71 @@
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
+/**
+ * Shared OpenAPI schemas surfaced by this plugin. Picked up by
+ * scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * BulkImportResult:
+ *   type: object
+ *   description: Summary returned after a bulk import operation.
+ *   required: [success, total, created, updated, skipped, failed, errors, details]
+ *   properties:
+ *     success:
+ *       type: boolean
+ *       description: True when no fatal error aborted the import early.
+ *     total:
+ *       type: integer
+ *       description: Total number of CSV data rows (excluding header).
+ *       example: 42
+ *     created:
+ *       type: integer
+ *       description: Entries successfully created (or counted in dry-run).
+ *       example: 38
+ *     updated:
+ *       type: integer
+ *       description: Existing entries updated.
+ *       example: 2
+ *     skipped:
+ *       type: integer
+ *       description: Existing entries skipped because `updateExisting` was false.
+ *       example: 1
+ *     failed:
+ *       type: integer
+ *       description: Rows that caused an error.
+ *       example: 1
+ *     errors:
+ *       type: array
+ *       items:
+ *         type: object
+ *         required: [line, error]
+ *         properties:
+ *           line:
+ *             type: integer
+ *             description: 1-based CSV line number (2 = first data row).
+ *           identifier:
+ *             type: string
+ *             description: Value of the main attribute for the failing row (if known).
+ *           error:
+ *             type: string
+ *             description: Error message.
+ *       example:
+ *         - line: 5
+ *           identifier: bob
+ *           error: 'Missing required attribute: mail'
+ *     details:
+ *       type: object
+ *       required: [duration, linesProcessed]
+ *       properties:
+ *         duration:
+ *           type: string
+ *           description: Wall-clock time for the import (e.g. `1.2s`).
+ *           example: 1.2s
+ *         linesProcessed:
+ *           type: integer
+ *           description: Total data rows attempted.
+ *           example: 42
+ */
 export default class LdapBulkImport extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -10,6 +10,74 @@ export interface postAdd {
     [key: string]: AttributeValue | undefined;
 }
 export type postModify = ModifyRequest;
+/**
+ * Shared OpenAPI schemas surfaced by this plugin. Picked up by
+ * scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * Group:
+ *   type: object
+ *   description: An LDAP group entry (groupOfNames / groupOfUniqueNames).
+ *   required: [dn, cn]
+ *   properties:
+ *     dn:
+ *       type: string
+ *       description: Fully-qualified distinguished name of the entry.
+ *       example: cn=admins,ou=groups,dc=example,dc=com
+ *     cn:
+ *       type: string
+ *       description: Common name (RDN attribute) of the group.
+ *       example: admins
+ *     description:
+ *       type: string
+ *       example: Server administrators
+ *     member:
+ *       type: array
+ *       items: { type: string }
+ *       description: DNs of the group's members.
+ *       example:
+ *         - uid=alice,ou=users,dc=example,dc=com
+ *         - uid=bob,ou=users,dc=example,dc=com
+ * GroupCreate:
+ *   type: object
+ *   required: [cn]
+ *   properties:
+ *     cn:
+ *       type: string
+ *       description: Common name of the new group.
+ *     description:
+ *       type: string
+ *     member:
+ *       type: array
+ *       items: { type: string }
+ *       description: Initial members (DNs).
+ *   example:
+ *     cn: admins
+ *     description: Server administrators
+ *     member:
+ *       - uid=alice,ou=users,dc=example,dc=com
+ * GroupModify:
+ *   type: object
+ *   description: |
+ *     Partial update. Each provided attribute is replaced wholesale. Use
+ *     the dedicated `/members` endpoints to add/remove members one at a
+ *     time without supplying the full list.
+ *   properties:
+ *     description: { type: string }
+ *     member:
+ *       type: array
+ *       items: { type: string }
+ *   example:
+ *     description: Updated description
+ * Error:
+ *   type: object
+ *   properties:
+ *     error: { type: string }
+ *     code: { type: integer }
+ *   example:
+ *     error: Group not found
+ *     code: 404
+ */
 export default class LdapGroups extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -1,65 +1,8 @@
-import type { Express, Request, Response } from 'express';
-import DmPlugin, { type Role } from '../../abstract/plugin';
-import { DM } from '../../bin';
-import { Hooks } from '../../hooks';
-import { AttributesList, AttributeValue, ModifyRequest } from '../../lib/ldapActions';
-import type { Schema } from '../../config/schema';
-export default class LdapOrganizations extends DmPlugin {
-    name: string;
-    roles: Role[];
-    pathAttr: string;
-    linkAttr: string;
-    schema?: Schema;
-    constructor(dm: DM);
-    /**
-     * API routes for LDAP organizations
-     * @param app Express application
-     */
-    api(app: Express): void;
-    apiAdd(req: Request, res: Response): Promise<void>;
-    apiModify(req: Request, res: Response): Promise<void>;
-    apiDelete(req: Request, res: Response): Promise<void>;
-    apiMove(req: Request, res: Response): Promise<void>;
-    /**
-     * Consistency checks on any entry
-     */
-    hooks: Hooks;
-    /**
-     * Check if the department link is valid
-     * @param entry LDAP entry to check
-     */
-    checkDeptLink(entry: AttributesList): Promise<void>;
-    /**
-     * Check if the department path is valid
-     * @param entry LDAP entry to check
-     */
-    checkDeptPath(entry: AttributesList): Promise<void>;
-    isEmptyOrganization(dn: string): Promise<void>;
-    /**
-     * Check if entry is an organisation
-     * @param entry LDAP entry to check
-     * @returns True if entry is an organisation, false otherwise
-     */
-    isOu(entry: AttributesList): boolean;
-    getOrganisationTop(req?: Request): Promise<AttributesList | AttributesList[]>;
-    getOrganisationByDn(dn: string, req?: Request): Promise<AttributesList>;
-    getOrganisationSubnodes(dn: string, req?: Request): Promise<AttributesList[]>;
-    addOrganization(dn: string, entry: AttributesList, req?: Request): Promise<boolean>;
-    modifyOrganization(dn: string, changes: ModifyRequest): Promise<boolean>;
-    validateNewOrganization(dn: string, entry: AttributesList): boolean;
-    validateChanges(dn: string, changes: ModifyRequest): boolean;
-    _validateOneChange(field: string, value: AttributeValue | null): boolean;
-    /**
-     * Move an organization to a different parent organization
-     * Uses LDAP modifyDN to change the DN hierarchy
-     */
-    moveOrganization(dn: string, targetOrgDn: string, req?: Request): Promise<{
-        newDn: string;
-    }>;
-    deleteOrganization(dn: string): Promise<boolean>;
-    searchOrganisationSubnodes(dn: string, query: string): Promise<AttributesList[]>;
-    /**
-     * Provide configuration for config API
-     */
-    getConfigApiData(): Record<string, unknown>;
-}
+/**
+ * @deprecated Use `core/ldap/organizations` instead. This file is a
+ * backwards-compatibility shim for setups that still load the plugin under
+ * the historical (singular) filename. It will be removed in a future major
+ * release.
+ */
+import LdapOrganizations from './organizations';
+export default LdapOrganizations;

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

@@ -0,0 +1,155 @@
+import type { Express, Request, Response } from 'express';
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import { DM } from '../../bin';
+import { Hooks } from '../../hooks';
+import { AttributesList, AttributeValue, ModifyRequest } from '../../lib/ldapActions';
+import type { Schema } from '../../config/schema';
+/**
+ * Shared OpenAPI schemas surfaced by this plugin. Picked up by
+ * scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * Organization:
+ *   type: object
+ *   description: An LDAP organizational unit entry.
+ *   required: [dn, ou]
+ *   properties:
+ *     dn:
+ *       type: string
+ *       description: Fully-qualified distinguished name of the entry.
+ *       example: ou=Engineering,ou=organizations,dc=example,dc=com
+ *     ou:
+ *       type: string
+ *       description: Organizational unit name (RDN attribute).
+ *       example: Engineering
+ *     o:
+ *       type: string
+ *       description: Organization display name.
+ *       example: Engineering Department
+ *     l:
+ *       type: string
+ *       description: Locality / city.
+ *       example: Paris
+ *     description:
+ *       type: string
+ *       example: Software engineering division
+ *     organizationLink:
+ *       type: string
+ *       description: DN of the parent organization (link attribute).
+ *       example: ou=organizations,dc=example,dc=com
+ *     organizationPath:
+ *       type: string
+ *       description: |
+ *         Human-readable slash-separated path to this node, used by the
+ *         UI tree. Set automatically on creation and move.
+ *       example: Engineering / Backend
+ *     member:
+ *       type: array
+ *       items: { type: string }
+ *       description: DNs of entries linked to this organization.
+ *       example:
+ *         - uid=alice,ou=users,dc=example,dc=com
+ * OrgSummary:
+ *   type: object
+ *   description: Lightweight organization reference (used in node lists).
+ *   required: [dn, ou]
+ *   properties:
+ *     dn: { type: string, example: ou=HR,ou=organizations,dc=example,dc=com }
+ *     ou: { type: string, example: HR }
+ *     description: { type: string }
+ *     objectClass:
+ *       type: array
+ *       items: { type: string }
+ *       example: [top, organizationalUnit]
+ * OrganizationCreate:
+ *   type: object
+ *   required: [ou]
+ *   properties:
+ *     ou:
+ *       type: string
+ *       description: Name of the new organizational unit.
+ *       example: Marketing
+ *     parentDn:
+ *       type: string
+ *       description: |
+ *         DN of the parent organizational unit. Defaults to the configured
+ *         top organization when omitted.
+ *       example: ou=organizations,dc=example,dc=com
+ *     description: { type: string }
+ *     l: { type: string }
+ *   example:
+ *     ou: Marketing
+ *     parentDn: ou=organizations,dc=example,dc=com
+ *     description: Marketing division
+ * OrganizationModify:
+ *   type: object
+ *   description: |
+ *     Partial update. Any provided attribute is replaced wholesale.
+ *     `ou` cannot be changed via this endpoint — use the move endpoint
+ *     to relocate the node within the tree.
+ *   properties:
+ *     description: { type: string }
+ *     l: { type: string }
+ *     o: { type: string }
+ *   example:
+ *     description: Updated description for Marketing
+ */
+export default class LdapOrganizations extends DmPlugin {
+    name: string;
+    roles: Role[];
+    pathAttr: string;
+    linkAttr: string;
+    schema?: Schema;
+    constructor(dm: DM);
+    /**
+     * API routes for LDAP organizations
+     * @param app Express application
+     */
+    api(app: Express): void;
+    apiAdd(req: Request, res: Response): Promise<void>;
+    apiModify(req: Request, res: Response): Promise<void>;
+    apiDelete(req: Request, res: Response): Promise<void>;
+    apiMove(req: Request, res: Response): Promise<void>;
+    /**
+     * Consistency checks on any entry
+     */
+    hooks: Hooks;
+    /**
+     * Check if the department link is valid
+     * @param entry LDAP entry to check
+     */
+    checkDeptLink(entry: AttributesList): Promise<void>;
+    /**
+     * Check if the department path is valid
+     * @param entry LDAP entry to check
+     */
+    checkDeptPath(entry: AttributesList): Promise<void>;
+    isEmptyOrganization(dn: string): Promise<void>;
+    /**
+     * Check if entry is an organisation
+     * @param entry LDAP entry to check
+     * @returns True if entry is an organisation, false otherwise
+     */
+    isOu(entry: AttributesList): boolean;
+    getOrganisationTop(req?: Request): Promise<AttributesList | AttributesList[]>;
+    getOrganisationByDn(dn: string, req?: Request): Promise<AttributesList>;
+    getOrganisationSubnodes(dn: string, req?: Request): Promise<AttributesList[]>;
+    addOrganization(dn: string, entry: AttributesList, req?: Request): Promise<boolean>;
+    modifyOrganization(dn: string, changes: ModifyRequest): Promise<boolean>;
+    validateNewOrganization(dn: string, entry: AttributesList): boolean;
+    validateChanges(dn: string, changes: ModifyRequest): boolean;
+    _validateOneChange(field: string, value: AttributeValue | null): boolean;
+    /**
+     * Move an organization to a different parent organization
+     * Uses LDAP modifyDN to change the DN hierarchy
+     */
+    moveOrganization(dn: string, targetOrgDn: string, req?: Request): Promise<{
+        newDn: string;
+    }>;
+    deleteOrganization(dn: string): Promise<boolean>;
+    searchOrganisationSubnodes(dn: string, query: string): Promise<AttributesList[]>;
+    /**
+     * Provide configuration for config API
+     */
+    getConfigApiData(): Record<string, unknown>;
+}