Secure LDAP TLS Client

from typing import Any, Dict, List, Optional, Protocol


class TLSConfig(Protocol):
    host: str
    port: int
    use_ssl: bool
    ca_cert_file: str
    client_cert_file: str
    client_key_file: str
    require_hostname_check: bool


def establish_session(config: TLSConfig, timeout: Optional[float] = None) -> Any:
    """
    Opens a TLS-secured LDAP session using the provided CA/client materials and returns a session handle
    that exposes whether TLS is active.
    Raises on TLS verification issues or bind failures.
    """


def certificate_bind(session: Any, authz_id: Optional[str] = None) -> str:
    """
    Performs a certificate-based bind on the existing TLS session without using a password.
    Optionally allows specifying an authorization identity to assert.
    Returns the bound identity string and raises if TLS is missing or client credentials are unusable.
    """


def search_entries(session: Any, base_dn: str, filter_expression: str, attributes: List[str]) -> List[Dict[str, Any]]:
    """
    Executes a subtree search using the authenticated session and returns entries with only requested attributes,
    formatted as dictionaries keyed by DN and attribute names.
    Raises if the search fails or when called on an unbound session.
    """