ldap-rest 0.4.6 → 0.5.0

package/dist/src/browser/ldap-browser/components/EntryTree.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Lazy directory tree: one root per exposed base, children fetched on expand.
+ * @module browser/ldap-browser/components/EntryTree
+ */
+import { DisposableComponent } from '../../shared/components/DisposableComponent';
+import type { RawApiClient } from '../api/RawApiClient';
+export declare class EntryTree extends DisposableComponent {
+    private container;
+    private api;
+    private onSelect;
+    private onError;
+    private roots;
+    private children;
+    private expanded;
+    private loading;
+    private selectedDn;
+    constructor(container: HTMLElement, api: RawApiClient, onSelect: (dn: string) => void | Promise<void>, onError: (error: Error) => void);
+    /**
+     * Load the exposed bases and draw them as roots.
+     *
+     * @param bases base DNs to use as roots
+     */
+    init(bases: string[]): Promise<void>;
+    /**
+     * DN currently highlighted in the tree.
+     *
+     * @returns selected DN, or null
+     */
+    getSelectedDn(): string | null;
+    /**
+     * Highlight an entry and notify the parent component.
+     *
+     * @param dn DN to select
+     * @returns whatever the selection handler returns, so callers can await
+     *          the entry actually being displayed
+     */
+    select(dn: string): void | Promise<void>;
+    /**
+     * Expand the tree down to a DN, loading every level on the way, then
+     * select it. Used to follow a search result or a DN typed by the user.
+     *
+     * @param dn DN to reveal
+     */
+    revealAndSelect(dn: string): Promise<void>;
+    /**
+     * Drop cached children so the next expand hits the server again.
+     *
+     * @param dn DN whose children must be reloaded, or undefined for all
+     */
+    invalidate(dn?: string): void;
+    /**
+     * Expand a node, fetching its children the first time.
+     *
+     * @param dn DN of the node
+     */
+    private expand;
+    /**
+     * Expand or collapse a node.
+     *
+     * @param dn DN of the node
+     */
+    private toggle;
+    /** Redraw the whole tree */
+    private render;
+    /**
+     * Render one node and, when expanded, its children.
+     *
+     * @param dn DN of the node
+     * @param label text shown for the node
+     * @param objectClass object classes, used to pick the icon
+     * @param expandable whether the node may have children
+     * @returns HTML of the node
+     */
+    private renderNode;
+}

package/dist/src/browser/ldap-browser/components/EntryView.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Attribute table of one entry, annotated with the directory schema.
+ * @module browser/ldap-browser/components/EntryView
+ */
+import type { SchemaView } from '../schema';
+import type { RawEntry } from '../types';
+export declare class EntryView {
+    private container;
+    private schema;
+    constructor(container: HTMLElement, schema: SchemaView | null);
+    /** Draw the placeholder shown when nothing is selected */
+    renderEmpty(): void;
+    /**
+     * Draw an error in place of the entry.
+     *
+     * @param message message to display
+     */
+    renderError(message: string): void;
+    /** Draw a loading indicator */
+    renderLoading(): void;
+    /**
+     * Draw an entry: its DN, its object classes with the attributes they allow,
+     * then the attribute table.
+     *
+     * @param entry entry to display
+     */
+    render(entry: RawEntry): void;
+    /**
+     * Render the object class list and, when the schema is available, the
+     * attributes those classes allow.
+     *
+     * @param objectClasses object classes of the entry
+     * @param resolved mandatory and optional attributes they imply
+     * @returns HTML of the section
+     */
+    private renderObjectClasses;
+    /**
+     * Render one attribute table.
+     *
+     * @param entry entry being displayed
+     * @param mandatory lowercase names of the mandatory attributes
+     * @param names attributes to include, in display order
+     * @param title heading of the table
+     * @returns HTML of the table
+     */
+    private renderTable;
+    /**
+     * Render the values of one attribute: images as thumbnails, other binary
+     * values as their size plus the base64 payload, text as text.
+     *
+     * @param name attribute name
+     * @param attribute values and binary flag
+     * @returns HTML of the value cell
+     */
+    private renderValues;
+}

package/dist/src/browser/ldap-browser/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * LDAP Browser - low-level directory browser (read-only)
+ * @author Xavier Guimard
+ */
+import './styles.css';
+export { LdapBrowser } from './LdapBrowser';
+export { RawApiClient } from './api/RawApiClient';
+export { SchemaView } from './schema';
+export type { BrowserOptions, LdapSchema, RawAttribute, RawChild, RawEntry, RawSearchResult, ObjectClassDefinition, AttributeTypeDefinition, } from './types';

package/dist/src/browser/ldap-browser/schema.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Client-side view of the directory schema: the lookups the UI needs to
+ * annotate an entry (mandatory attributes, descriptions, binary values).
+ *
+ * This mirrors `src/lib/ldapSchema.ts` on the server, minus the parsing:
+ * the browser receives the schema already parsed.
+ *
+ * @module browser/ldap-browser/schema
+ */
+import type { AttributeTypeDefinition, LdapSchema, ObjectClassDefinition } from './types';
+export declare class SchemaView {
+    readonly schema: LdapSchema;
+    private objectClasses;
+    private attributeTypes;
+    constructor(schema: LdapSchema);
+    /**
+     * Look up an object class by name or OID.
+     *
+     * @param name object class name or OID
+     * @returns the definition, or undefined when unknown
+     */
+    getObjectClass(name: string): ObjectClassDefinition | undefined;
+    /**
+     * Look up an attribute type by name or OID, ignoring attribute options.
+     *
+     * @param name attribute name, `;binary` and friends included
+     * @returns the definition, or undefined when unknown
+     */
+    getAttributeType(name: string): AttributeTypeDefinition | undefined;
+    /**
+     * Resolve the syntax of an attribute through its `SUP` chain.
+     *
+     * @param name attribute name
+     * @returns syntax OID, or undefined
+     */
+    getAttributeSyntax(name: string): string | undefined;
+    /**
+     * Tell whether an attribute is meant to be displayed as an image.
+     *
+     * @param name attribute name
+     * @returns true for photo-like attributes
+     */
+    isImageAttribute(name: string): boolean;
+    /**
+     * Tell whether an attribute holds octets rather than text.
+     *
+     * @param name attribute name
+     * @returns true when values are binary
+     */
+    isBinaryAttribute(name: string): boolean;
+    /**
+     * Collect the mandatory and optional attributes of a set of object
+     * classes, walking every `SUP` chain.
+     *
+     * @param objectClasses object class names carried by an entry
+     * @returns `must` and `may` attribute names, `may` excluding mandatory ones
+     */
+    resolveAttributes(objectClasses: string[]): {
+        must: string[];
+        may: string[];
+    };
+}

package/dist/src/browser/ldap-browser/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Types of the low-level LDAP browser, mirroring the responses of the
+ * `core/ldap/raw` server plugin.
+ * @module browser/ldap-browser/types
+ */
+/** Values of a single attribute; base64-encoded when `binary` is true */
+export interface RawAttribute {
+    values: string[];
+    binary: boolean;
+}
+/** A directory entry with all its attributes */
+export interface RawEntry {
+    dn: string;
+    attributes: Record<string, RawAttribute>;
+}
+/** Direct child of an entry, as needed to draw a tree node */
+export interface RawChild {
+    dn: string;
+    rdn: string;
+    objectClass: string[];
+    hasChildren: boolean;
+}
+/** Direct children of an entry, with the truncation flag */
+export interface RawChildren {
+    children: RawChild[];
+    /** True when the server's result limit cut the listing short */
+    truncated: boolean;
+}
+/** Result of a raw search */
+export interface RawSearchResult {
+    entries: RawEntry[];
+    truncated: boolean;
+}
+/** Parsed `objectClasses` definition */
+export interface ObjectClassDefinition {
+    oid: string;
+    names: string[];
+    desc?: string;
+    obsolete: boolean;
+    sup: string[];
+    kind: 'STRUCTURAL' | 'ABSTRACT' | 'AUXILIARY';
+    must: string[];
+    may: string[];
+}
+/** Parsed `attributeTypes` definition */
+export interface AttributeTypeDefinition {
+    oid: string;
+    names: string[];
+    desc?: string;
+    obsolete: boolean;
+    sup?: string;
+    equality?: string;
+    ordering?: string;
+    substr?: string;
+    syntax?: string;
+    syntaxLength?: number;
+    singleValue: boolean;
+    collective: boolean;
+    noUserModification: boolean;
+    usage: string;
+}
+/** Parsed `ldapSyntaxes` definition */
+export interface SyntaxDefinition {
+    oid: string;
+    desc?: string;
+    binary: boolean;
+}
+/** Parsed `matchingRules` definition */
+export interface MatchingRuleDefinition {
+    oid: string;
+    names: string[];
+    desc?: string;
+    syntax?: string;
+}
+/** Whole schema as served by `GET /api/v1/ldap/raw/schema` */
+export interface LdapSchema {
+    objectClasses: ObjectClassDefinition[];
+    attributeTypes: AttributeTypeDefinition[];
+    syntaxes: SyntaxDefinition[];
+    matchingRules: MatchingRuleDefinition[];
+}
+/** Options of the {@link LdapBrowser} constructor */
+export interface BrowserOptions {
+    /** id of the element the browser renders into */
+    containerId: string;
+    /** Origin of the API, e.g. `window.location.origin` */
+    apiBaseUrl?: string;
+    /** Bearer token sent with every request */
+    authToken?: string;
+    /** DN to select on startup; defaults to the first exposed base */
+    initialDn?: string;
+    /** Called whenever an entry is displayed */
+    onEntrySelected?: (dn: string) => void;
+    /** Called on any error the browser handles itself */
+    onError?: (error: Error) => void;
+}

package/dist/src/config/args.d.ts

@@ -58,6 +58,11 @@ export interface Config {
     ldap_organization_max_subnodes?: number;
     organization_schema?: string;
     ldap_flat_schema?: string[];
+    ldap_raw_base?: string[];
+    ldap_raw_hidden_attribute?: string[];
+    ldap_raw_show_secrets?: boolean;
+    ldap_raw_max_results?: number;
+    ldap_raw_schema_cache_ttl?: number;
     bulk_import_schemas?: string;
     bulk_import_max_file_size?: string;
     bulk_import_batch_size?: string;
@@ -65,6 +70,7 @@ export interface Config {
     external_branch_class?: string[];
     static_path?: string;
     static_name?: string;
+    auth_path_prefix?: string | string[];
     llng_ini?: string;
     auth_token?: string[];
     auth_totp?: string[];

package/dist/src/lib/auth/base.d.ts

@@ -3,7 +3,88 @@ export type DmRequest = Request & {
     user?: string;
 };
 import DmPlugin from '../../abstract/plugin';
+/**
+ * Tell whether a mount prefix covers a request path, with the rule Express
+ * itself applies: on segment boundaries, so `/api/m` covers `/api/m` and
+ * `/api/m/entry` but never `/api/machines`.
+ *
+ * The catch-all uses this to decide what another plugin already guards, so
+ * it must agree with Express exactly — a looser rule here would skip paths
+ * nobody guards.
+ *
+ * @param prefix mount prefix
+ * @param path request path
+ * @returns true when the prefix covers the path
+ */
+export declare function prefixCoversPath(prefix: string, path: string): boolean;
+/**
+ * Path prefixes claimed by scoped authentication plugins.
+ *
+ * Takes the registry as an argument rather than reaching for the server, so
+ * `DM` and `AuthBase` share one definition of what "claimed" means. The
+ * registry is a live reference: it keeps filling as the remaining plugins
+ * register, which is why the catch-all consults it per request.
+ *
+ * @param loadedPlugins the server's plugin registry
+ * @param except name of the plugin asking, excluded from the result
+ * @returns the prefixes other authentication plugins guard
+ */
+export declare function claimedPrefixes(loadedPlugins: Record<string, DmPlugin>, except?: string): string[];
 export default abstract class AuthBase extends DmPlugin {
     abstract authMethod(req: DmRequest, res: Response, next: () => void): void;
-    api(app: Express): void;
+    /** Validated prefixes, computed once: the catch-all reads them per request */
+    private _pathPrefixes?;
+    /**
+     * Path prefixes this authentication applies to, empty when it guards the
+     * whole server.
+     *
+     * Loading the same plugin twice with different prefixes lets one server
+     * serve populations that authenticate differently — machines with a token
+     * on one branch of the API, administrators with an SSO session on another:
+     *
+     * ```
+     * --plugin 'core/auth/token:tok:{"auth_path_prefix":"/api/m"}'
+     * --plugin 'core/auth/openidconnect:oidc:{"auth_path_prefix":"/api/admin"}'
+     * ```
+     *
+     * A credential is then only valid on the branch it was scoped to, which is
+     * the point: a leaked machine token buys nothing on the admin API.
+     *
+     * A malformed entry is refused rather than skipped. Dropping one silently
+     * would shrink what the plugin guards — the failure mode that leaves a
+     * branch open while the configuration still reads as if it were covered.
+     *
+     * `/` is not a prefix but the whole server, so a list containing it makes
+     * the plugin a catch-all: `["/", "/api/admin"]` guards everything, not
+     * only `/api/admin`.
+     *
+     * @returns the configured prefixes without their trailing slashes, empty
+     *          when the plugin guards the whole server
+     * @throws Error when an entry is not a usable path prefix
+     */
+    get pathPrefixes(): string[];
+    /**
+     * Run this plugin's authentication on a request, hooks included.
+     *
+     * The dispatcher calls this; the plugin no longer owns a layer of its own.
+     *
+     * @param req incoming request
+     * @param res response, ended here when authentication fails
+     * @param next called only when the request is authenticated
+     */
+    authenticate(req: Request, res: Response, next: () => void): Promise<void>;
+    /**
+     * Register with the server's authentication dispatcher instead of mounting
+     * a middleware.
+     *
+     * Mounting per plugin made protection depend on registration order: a
+     * plugin whose `app.use` landed after the routes it was meant to guard
+     * never ran for them, and the catch-all — stepping aside for a branch that
+     * guard was supposed to cover — turned that into anonymous access. The
+     * dispatcher is mounted by `DM` before any plugin loads, so it always
+     * precedes every route, whatever order the plugins register in.
+     *
+     * @param _app unused: the dispatcher owns the only authentication layer
+     */
+    api(_app: Express): void;
 }

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

@@ -0,0 +1,159 @@
+/**
+ * LDAP schema (RFC 4512) parser
+ *
+ * The directory publishes its schema as a set of string definitions in the
+ * subschema entry (`objectClasses`, `attributeTypes`, `ldapSyntaxes`,
+ * `matchingRules`). This module turns those strings into plain objects and
+ * resolves the inheritance chains, so a client can know which attributes an
+ * entry may carry, which ones are mandatory, and how to render their values.
+ *
+ * @module lib/ldapSchema
+ * @author Xavier Guimard <xguimard@linagora.com>
+ */
+/** Parsed `attributeTypes` definition (RFC 4512 §4.1.2) */
+export interface AttributeTypeDefinition {
+    oid: string;
+    names: string[];
+    desc?: string;
+    obsolete: boolean;
+    sup?: string;
+    equality?: string;
+    ordering?: string;
+    substr?: string;
+    syntax?: string;
+    /** Suggested maximum length, from the `{len}` suffix of the syntax OID */
+    syntaxLength?: number;
+    singleValue: boolean;
+    collective: boolean;
+    noUserModification: boolean;
+    /** `userApplications` (default), `directoryOperation`, `distributedOperation` or `dSAOperation` */
+    usage: string;
+}
+/** Parsed `objectClasses` definition (RFC 4512 §4.1.1) */
+export interface ObjectClassDefinition {
+    oid: string;
+    names: string[];
+    desc?: string;
+    obsolete: boolean;
+    sup: string[];
+    kind: 'STRUCTURAL' | 'ABSTRACT' | 'AUXILIARY';
+    must: string[];
+    may: string[];
+}
+/** Parsed `ldapSyntaxes` definition (RFC 4512 §4.1.5) */
+export interface SyntaxDefinition {
+    oid: string;
+    desc?: string;
+    /** True when values of this syntax are not human-readable text */
+    binary: boolean;
+}
+/** Parsed `matchingRules` definition (RFC 4512 §4.1.3) */
+export interface MatchingRuleDefinition {
+    oid: string;
+    names: string[];
+    desc?: string;
+    syntax?: string;
+}
+/** Whole schema, indexed by lowercase name for lookups */
+export interface LdapSchema {
+    attributeTypes: AttributeTypeDefinition[];
+    objectClasses: ObjectClassDefinition[];
+    syntaxes: SyntaxDefinition[];
+    matchingRules: MatchingRuleDefinition[];
+}
+/** Raw definitions as read from the subschema entry */
+export interface RawSchemaDefinitions {
+    attributeTypes?: string[];
+    objectClasses?: string[];
+    ldapSyntaxes?: string[];
+    matchingRules?: string[];
+}
+/**
+ * Parse an `attributeTypes` definition.
+ *
+ * @param definition definition string
+ * @returns parsed definition, or null when it cannot be parsed
+ */
+export declare function parseAttributeType(definition: string): AttributeTypeDefinition | null;
+/**
+ * Parse an `objectClasses` definition.
+ *
+ * @param definition definition string
+ * @returns parsed definition, or null when it cannot be parsed
+ */
+export declare function parseObjectClass(definition: string): ObjectClassDefinition | null;
+/**
+ * Parse an `ldapSyntaxes` definition.
+ *
+ * @param definition definition string
+ * @returns parsed definition, or null when it cannot be parsed
+ */
+export declare function parseSyntax(definition: string): SyntaxDefinition | null;
+/**
+ * Parse a `matchingRules` definition.
+ *
+ * @param definition definition string
+ * @returns parsed definition, or null when it cannot be parsed
+ */
+export declare function parseMatchingRule(definition: string): MatchingRuleDefinition | null;
+/**
+ * Parse the four definition lists of a subschema entry. Unparseable
+ * definitions are skipped rather than failing the whole schema.
+ *
+ * @param raw definition strings as read from the subschema entry
+ * @returns parsed schema
+ */
+export declare function parseSchema(raw: RawSchemaDefinitions): LdapSchema;
+/**
+ * Indexed view of a schema, with the lookups a client needs: resolution of
+ * object class inheritance and detection of binary attributes.
+ */
+export declare class SchemaIndex {
+    readonly schema: LdapSchema;
+    private objectClassesByName;
+    private attributeTypesByName;
+    private syntaxesByOid;
+    constructor(schema: LdapSchema);
+    /**
+     * Look up an object class by name or OID (case-insensitive).
+     *
+     * @param name object class name or OID
+     * @returns the definition, or undefined when unknown
+     */
+    getObjectClass(name: string): ObjectClassDefinition | undefined;
+    /**
+     * Look up an attribute type by name or OID (case-insensitive).
+     *
+     * @param name attribute name or OID
+     * @returns the definition, or undefined when unknown
+     */
+    getAttributeType(name: string): AttributeTypeDefinition | undefined;
+    /**
+     * Resolve the syntax of an attribute, following the `SUP` chain when the
+     * attribute does not declare one itself.
+     *
+     * @param name attribute name or OID
+     * @returns syntax OID, or undefined when it cannot be resolved
+     */
+    getAttributeSyntax(name: string): string | undefined;
+    /**
+     * Tell whether an attribute holds octets rather than text, and therefore
+     * must be base64-encoded in JSON.
+     *
+     * @param name attribute name, options included (`jpegPhoto;binary`)
+     * @returns true when values must be treated as binary
+     */
+    isBinaryAttribute(name: string): boolean;
+    /**
+     * Collect the mandatory and optional attributes of a set of object classes,
+     * walking every `SUP` chain.
+     *
+     * @param objectClasses object class names carried by an entry
+     * @returns deduplicated `must` and `may` attribute names, `may` excluding
+     *          anything already mandatory
+     */
+    resolveAttributes(objectClasses: string[]): {
+        must: string[];
+        may: string[];
+    };
+}