ldap-cli 0.2.0__py3-none-any.whl

ldapc/cli.py

@@ -0,0 +1,490 @@
+"""CLI entry point for ldapc.
+
+Provides the argument parser and main entry point for the ldapc
+command-line tool. Uses subcommands for LDAP operations:
+
+    ldapc list users|groups
+    ldapc search user|group <term>
+    ldapc get user|group <name>
+    ldapc add user|group <name>
+    ldapc delete user|group <name>
+    ldapc user add group <user> <group>
+    ldapc user remove group <user> <group>
+    ldapc configure
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+
+from ldapc import __version__
+from ldapc.exceptions import (
+    AuthenticationError,
+    ConfigError,
+    ConnectionError,
+)
+
+LOG = logging.getLogger("ldapc")
+
+ENV_SKIP_SSL_VERIFY = "LDAPC_SKIP_SSL_VERIFY"
+
+
+def _env_skip_ssl() -> bool:
+    """Check if SSL verification should be skipped via environment variable."""
+    return os.environ.get(ENV_SKIP_SSL_VERIFY, "").lower() in ("1", "true", "yes")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser with subcommands."""
+    # Shared flags available on all subcommands
+    shared = argparse.ArgumentParser(add_help=False)
+    shared.add_argument(
+        "--debug",
+        action="store_true",
+        default=None,
+        help="Enable debug logging for troubleshooting.",
+    )
+    shared.add_argument(
+        "--skip-ssl-verify",
+        action="store_true",
+        default=None,
+        help=f"Skip TLS certificate verification (env: {ENV_SKIP_SSL_VERIFY}).",
+    )
+    shared.add_argument(
+        "--json",
+        action="store_true",
+        default=None,
+        help="Output results as JSON.",
+    )
+    shared.add_argument(
+        "--yaml",
+        action="store_true",
+        default=None,
+        help="Output results as YAML (simplified, human-friendly).",
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="ldapc",
+        description="Query and manage LDAP directories.",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"ldapc {__version__}",
+    )
+
+    parser.add_argument(
+        "--docs",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="FILE",
+        help="View bundled documentation. Without FILE, lists available docs. With FILE, renders it.",
+    )
+
+    parser.add_argument(
+        "--page",
+        action="store_true",
+        help="Enable paging when viewing docs (use with --docs).",
+    )
+
+    parser.add_argument(
+        "--markdown",
+        action="store_true",
+        help="Render docs as raw markdown instead of rich text (use with --docs).",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # ldapc configure
+    subparsers.add_parser("configure", parents=[shared], help="Set up host, bind DN, base DN, and password.")
+
+    # ldapc list users|groups
+    list_parser = subparsers.add_parser("list", parents=[shared], help="List all users or groups.")
+    list_parser.add_argument("type", choices=["users", "groups"], help="What to list.")
+
+    # ldapc search user|group <term>
+    search_parser = subparsers.add_parser("search", parents=[shared], help="Search for users or groups.")
+    search_parser.add_argument("type", choices=["user", "group"], help="What to search.")
+    search_parser.add_argument("term", help="Search term (case-insensitive substring match).")
+
+    # ldapc get user|group <name>
+    get_parser = subparsers.add_parser("get", parents=[shared], help="Get details of a user or group.")
+    get_parser.add_argument("type", choices=["user", "group"], help="What to get.")
+    get_parser.add_argument("name", help="Exact cn or uid to look up.")
+
+    # ldapc add user|group <name>
+    add_parser = subparsers.add_parser("add", parents=[shared], help="Add a user or group.")
+    add_parser.add_argument("type", choices=["user", "group"], help="What to add.")
+    add_parser.add_argument("name", help="Name of the user or group to create.")
+
+    # ldapc delete user|group <name>
+    delete_parser = subparsers.add_parser("delete", parents=[shared], help="Delete a user or group.")
+    delete_parser.add_argument("type", choices=["user", "group"], help="What to delete.")
+    delete_parser.add_argument("name", help="Name of the user or group to delete.")
+
+    # ldapc user add|remove group <user> <group>
+    user_parser = subparsers.add_parser("user", parents=[shared], help="Manage user group membership.")
+    user_sub = user_parser.add_subparsers(dest="action")
+
+    user_add_parser = user_sub.add_parser("add", parents=[shared], help="Add user to a group.")
+    user_add_parser.add_argument("target", choices=["group"], help="Must be 'group'.")
+    user_add_parser.add_argument("user", help="User to add.")
+    user_add_parser.add_argument("group", help="Group to add the user to.")
+
+    user_remove_parser = user_sub.add_parser("remove", parents=[shared], help="Remove user from a group.")
+    user_remove_parser.add_argument("target", choices=["group"], help="Must be 'group'.")
+    user_remove_parser.add_argument("user", help="User to remove.")
+    user_remove_parser.add_argument("group", help="Group to remove the user from.")
+
+    return parser
+
+
+def _get_docs_dir() -> Path:
+    """Locate the docs directory bundled with the installed package.
+
+    Searches the package's installed location for .md files at the
+    top level and in a docs/ subdirectory.
+
+    Returns:
+        Path to the package's site-packages directory.
+    """
+    import importlib.resources
+
+    # The package root in site-packages
+    package_dir = Path(__file__).resolve().parent.parent
+    return package_dir
+
+
+def _find_doc_files() -> list[str]:
+    """Find all .md files bundled with the package."""
+    base = _get_docs_dir()
+    md_files: list[str] = []
+
+    # Top-level .md files
+    for f in sorted(base.glob("*.md")):
+        md_files.append(f.name)
+
+    # docs/ subdirectory
+    docs_dir = base / "docs"
+    if docs_dir.is_dir():
+        for f in sorted(docs_dir.glob("*.md")):
+            md_files.append(f"docs/{f.name}")
+
+    return md_files
+
+
+def _resolve_doc_path(filename: str) -> Path | None:
+    """Resolve a doc filename to its full path."""
+    base = _get_docs_dir()
+    candidate = base / filename
+    if candidate.is_file():
+        return candidate
+    return None
+
+
+def _handle_docs(filename: str | None, page: bool, markdown: bool) -> None:
+    """Handle the --docs flag.
+
+    If filename is empty/None, list available docs.
+    Otherwise render the specified file.
+    """
+    if not filename:
+        # List available docs
+        files = _find_doc_files()
+        if not files:
+            print("No documentation files found.")
+            sys.exit(1)
+        print("Available documentation:")
+        print()
+        for f in files:
+            print(f"  {f}")
+        print()
+        print("Usage: ldapc --docs <filename>")
+        return
+
+    doc_path = _resolve_doc_path(filename)
+    if doc_path is None:
+        print(f"Documentation file not found: {filename}", file=sys.stderr)
+        print("Run 'ldapc --docs' to see available files.", file=sys.stderr)
+        sys.exit(1)
+
+    content = doc_path.read_text(encoding="utf-8")
+
+    if markdown:
+        # Raw markdown output
+        if page:
+            _page_text(content)
+        else:
+            print(content)
+    else:
+        # Rich rendered output
+        _render_rich(content, page)
+
+
+def _render_rich(content: str, page: bool) -> None:
+    """Render markdown content using rich."""
+    from rich.console import Console
+    from rich.markdown import Markdown
+
+    md = Markdown(content)
+
+    if page:
+        with Console() as console:
+            with console.pager(styles=True):
+                console.print(md)
+    else:
+        console = Console()
+        console.print(md)
+
+
+def _page_text(text: str) -> None:
+    """Display text with paging."""
+    import pydoc
+    pydoc.pager(text)
+
+
+def _get_client(skip_ssl_verify: bool):
+    """Load config and return a connected LdapClient."""
+    from ldapc.config import load_config, retrieve_password
+    from ldapc.ldap_client import LdapClient
+
+    config = load_config()
+    password = retrieve_password(config.username)
+
+    LOG.debug("Connecting to %s as %s", config.host, config.username)
+    LOG.debug("Base DN: %s", config.base_dn)
+    if skip_ssl_verify:
+        LOG.debug("TLS certificate verification disabled")
+
+    client = LdapClient(config.host, config.username, password, skip_ssl_verify=skip_ssl_verify)
+    return client, config
+
+
+def _handle_configure() -> None:
+    """Run the interactive configuration flow."""
+    from ldapc.config import save_config, store_password, LdapcConfig
+    import getpass
+
+    host = input("LDAP host URL: ")
+    base_dn = input("Base DN: ")
+    username = input("Bind DN: ")
+    users_ou = input("Users container RDN [cn=users]: ").strip() or "cn=users"
+    groups_ou = input("Groups container RDN [cn=groups]: ").strip() or "cn=groups"
+    password = getpass.getpass("Bind password: ")
+
+    config = LdapcConfig(host=host, username=username, base_dn=base_dn,
+                         users_ou=users_ou, groups_ou=groups_ou)
+    save_config(config)
+    store_password(username, password)
+    LOG.debug("Configuration saved to ~/.ldapc/config.yaml")
+    print("Configuration saved.")
+
+
+def _handle_list(args) -> None:
+    """Handle: ldapc list users|groups"""
+    from ldapc.formatter import (
+        format_user_entries, format_group_entries, format_entries_json,
+        format_user_entries_yaml, format_group_entries_yaml,
+    )
+
+    client, config = _get_client(args.skip_ssl_verify)
+    with client:
+        if args.type == "users":
+            entries = client.list_users(config.base_dn)
+        else:
+            entries = client.list_groups(config.base_dn)
+
+    LOG.debug("List returned %d entries", len(entries))
+
+    if not entries:
+        print(f"No {args.type} found.")
+        return
+
+    if args.json:
+        print(format_entries_json(entries))
+    elif args.yaml:
+        if args.type == "users":
+            print(format_user_entries_yaml(entries))
+        else:
+            print(format_group_entries_yaml(entries))
+    elif args.type == "users":
+        print(format_user_entries(entries))
+    else:
+        print(format_group_entries(entries))
+
+
+def _handle_search(args) -> None:
+    """Handle: ldapc search user|group <term>"""
+    from ldapc.formatter import (
+        format_user_entries, format_group_entries, format_entries_json,
+        format_user_entries_yaml, format_group_entries_yaml,
+    )
+
+    client, config = _get_client(args.skip_ssl_verify)
+    with client:
+        if args.type == "user":
+            entries = client.search_users(args.term, config.base_dn)
+        else:
+            entries = client.search_groups(args.term, config.base_dn)
+
+    LOG.debug("Search returned %d entries", len(entries))
+
+    if not entries:
+        print(f"No results found for '{args.term}'")
+        return
+
+    if args.json:
+        print(format_entries_json(entries))
+    elif args.yaml:
+        if args.type == "user":
+            print(format_user_entries_yaml(entries))
+        else:
+            print(format_group_entries_yaml(entries))
+    elif args.type == "user":
+        print(format_user_entries(entries))
+    else:
+        print(format_group_entries(entries))
+
+
+def _handle_get(args) -> None:
+    """Handle: ldapc get user|group <name>"""
+    from ldapc.formatter import (
+        format_user_entries, format_group_entries, format_entries_json,
+        format_user_entries_yaml, format_group_entries_yaml,
+    )
+
+    client, config = _get_client(args.skip_ssl_verify)
+    with client:
+        if args.type == "user":
+            entries = client.get_user(args.name, config.base_dn)
+        else:
+            entries = client.get_group(args.name, config.base_dn)
+
+    if not entries:
+        print(f"No {args.type} found: '{args.name}'")
+        sys.exit(1)
+
+    if args.json:
+        print(format_entries_json(entries))
+    elif args.yaml:
+        if args.type == "user":
+            print(format_user_entries_yaml(entries))
+        else:
+            print(format_group_entries_yaml(entries))
+    elif args.type == "user":
+        print(format_user_entries(entries))
+    else:
+        print(format_group_entries(entries))
+
+
+def _handle_add(args) -> None:
+    """Handle: ldapc add user|group <name>"""
+    client, config = _get_client(args.skip_ssl_verify)
+    with client:
+        if args.type == "user":
+            client.add_user(args.name, config.base_dn, config.users_ou)
+        else:
+            client.add_group(args.name, config.base_dn, config.groups_ou)
+
+    print(f"{args.type.capitalize()} '{args.name}' added.")
+
+
+def _handle_delete(args) -> None:
+    """Handle: ldapc delete user|group <name>"""
+    client, config = _get_client(args.skip_ssl_verify)
+    with client:
+        if args.type == "user":
+            client.delete_user(args.name, config.base_dn, config.users_ou)
+        else:
+            client.delete_group(args.name, config.base_dn, config.groups_ou)
+
+    print(f"{args.type.capitalize()} '{args.name}' deleted.")
+
+
+def _handle_user_group(args) -> None:
+    """Handle: ldapc user add|remove group <user> <group>"""
+    client, config = _get_client(args.skip_ssl_verify)
+    with client:
+        if args.action == "add":
+            client.add_user_to_group(args.user, args.group, config.base_dn,
+                                     config.users_ou, config.groups_ou)
+            print(f"User '{args.user}' added to group '{args.group}'.")
+        elif args.action == "remove":
+            client.remove_user_from_group(args.user, args.group, config.base_dn,
+                                          config.users_ou, config.groups_ou)
+            print(f"User '{args.user}' removed from group '{args.group}'.")
+
+
+def main() -> None:
+    """Entry point registered as console script `ldapc`.
+
+    Parses arguments, dispatches to the appropriate handler, and maps
+    exceptions to exit codes:
+        - ConfigError → exit 2
+        - ConnectionError → exit 1
+        - AuthenticationError → exit 1
+    """
+    parser = build_parser()
+
+    if len(sys.argv) == 1:
+        parser.print_help(sys.stdout)
+        sys.exit(0)
+
+    args = parser.parse_args()
+
+    # Handle --docs before anything else (top-level flag)
+    if args.docs is not None:
+        _handle_docs(args.docs, args.page, args.markdown)
+        sys.exit(0)
+
+    # Resolve boolean flags (None means not explicitly set)
+    args.debug = bool(args.debug)
+    args.json = bool(args.json)
+    args.yaml = bool(args.yaml)
+    args.skip_ssl_verify = bool(args.skip_ssl_verify) or _env_skip_ssl()
+
+    if args.debug:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(name)s %(levelname)s: %(message)s",
+            stream=sys.stderr,
+        )
+    else:
+        logging.basicConfig(
+            level=logging.WARNING,
+            format="%(name)s %(levelname)s: %(message)s",
+            stream=sys.stderr,
+        )
+
+    try:
+        if args.command == "configure":
+            _handle_configure()
+        elif args.command == "list":
+            _handle_list(args)
+        elif args.command == "search":
+            _handle_search(args)
+        elif args.command == "get":
+            _handle_get(args)
+        elif args.command == "add":
+            _handle_add(args)
+        elif args.command == "delete":
+            _handle_delete(args)
+        elif args.command == "user":
+            if not args.action:
+                parser.parse_args(["user", "--help"])
+            _handle_user_group(args)
+        else:
+            parser.print_help(sys.stdout)
+            sys.exit(0)
+    except ConfigError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(2)
+    except (ConnectionError, AuthenticationError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)

ldapc/config.py

@@ -0,0 +1,184 @@
+"""Configuration management for ldapc.
+
+Handles reading, writing, and validating the ldapc configuration file
+stored at ~/.ldapc/config.yaml. Provides serialization between
+LdapcConfig dataclass instances and YAML format.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+import keyring
+import yaml
+
+from ldapc.exceptions import ConfigError
+
+DEFAULT_CONFIG_DIR = Path.home() / ".ldapc"
+DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_DIR / "config.yaml"
+
+
+@dataclass
+class LdapcConfig:
+    """Configuration object for ldapc.
+
+    Attributes:
+        host: LDAP server URL (ldaps:// or ldap://).
+        username: Bind DN for authentication.
+        base_dn: Base DN for searches. Defaults to empty string.
+        users_ou: RDN for the users container. Defaults to "cn=users".
+        groups_ou: RDN for the groups container. Defaults to "cn=groups".
+    """
+
+    host: str
+    username: str
+    base_dn: str = ""
+    users_ou: str = "cn=users"
+    groups_ou: str = "cn=groups"
+
+
+def config_to_yaml(config: LdapcConfig) -> str:
+    """Serialize a config object to a YAML string.
+
+    Args:
+        config: The LdapcConfig instance to serialize.
+
+    Returns:
+        A YAML-formatted string representing the configuration.
+    """
+    data = {
+        "host": config.host,
+        "username": config.username,
+        "base_dn": config.base_dn,
+        "users_ou": config.users_ou,
+        "groups_ou": config.groups_ou,
+    }
+    return yaml.dump(data, default_flow_style=False, sort_keys=False)
+
+
+def yaml_to_config(yaml_str: str) -> LdapcConfig:
+    """Parse a YAML string into a config object.
+
+    Args:
+        yaml_str: A YAML-formatted string to parse.
+
+    Returns:
+        An LdapcConfig instance populated from the YAML data.
+
+    Raises:
+        ConfigError: If the YAML is invalid or missing required fields.
+    """
+    try:
+        data = yaml.safe_load(yaml_str)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Invalid YAML in configuration: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError(
+            "Invalid configuration file: expected a YAML mapping, "
+            f"got {type(data).__name__}"
+        )
+
+    missing_fields = []
+    for field in ("host", "username"):
+        if field not in data:
+            missing_fields.append(field)
+
+    if missing_fields:
+        raise ConfigError(
+            f"Missing required configuration fields: {', '.join(missing_fields)}"
+        )
+
+    return LdapcConfig(
+        host=str(data["host"]),
+        username=str(data["username"]),
+        base_dn=str(data.get("base_dn", "")),
+        users_ou=str(data.get("users_ou", "cn=users")),
+        groups_ou=str(data.get("groups_ou", "cn=groups")),
+    )
+
+
+def load_config(config_path: Path | None = None) -> LdapcConfig:
+    """Load configuration from ~/.ldapc/config.yaml.
+
+    Args:
+        config_path: Optional path to the config file. Defaults to
+            ~/.ldapc/config.yaml.
+
+    Returns:
+        An LdapcConfig instance loaded from the file.
+
+    Raises:
+        ConfigError: If the file is missing or contains invalid YAML.
+    """
+    path = config_path or DEFAULT_CONFIG_PATH
+
+    if not path.exists():
+        raise ConfigError(
+            "Configuration not found. Run 'ldapc configure' to set up."
+        )
+
+    try:
+        yaml_str = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"Unable to read configuration file: {exc}") from exc
+
+    return yaml_to_config(yaml_str)
+
+
+def save_config(config: LdapcConfig, config_path: Path | None = None) -> None:
+    """Serialize config to ~/.ldapc/config.yaml with 0600 permissions.
+
+    Creates the ~/.ldapc/ directory if it does not exist.
+
+    Args:
+        config: The LdapcConfig instance to persist.
+        config_path: Optional path to the config file. Defaults to
+            ~/.ldapc/config.yaml.
+    """
+    path = config_path or DEFAULT_CONFIG_PATH
+    config_dir = path.parent
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    yaml_str = config_to_yaml(config)
+    path.write_text(yaml_str, encoding="utf-8")
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+
+
+KEYRING_SERVICE = "ldapc"
+
+
+def store_password(username: str, password: str) -> None:
+    """Store password in OS keychain under service 'ldapc'.
+
+    Args:
+        username: The account identifier (bind DN) to associate with
+            the stored password.
+        password: The password to store securely.
+    """
+    keyring.set_password(KEYRING_SERVICE, username, password)
+
+
+def retrieve_password(username: str) -> str:
+    """Retrieve password from OS keychain.
+
+    Args:
+        username: The account identifier (bind DN) whose password
+            should be retrieved.
+
+    Returns:
+        The stored password string.
+
+    Raises:
+        ConfigError: If no password is stored for the account.
+    """
+    password = keyring.get_password(KEYRING_SERVICE, username)
+    if password is None:
+        raise ConfigError(
+            "No stored password. Run 'ldapc configure' to set up."
+        )
+    return password

ldapc/exceptions.py

@@ -0,0 +1,37 @@
+"""Exception classes for ldapc.
+
+All exceptions inherit from LdapcError, enabling consistent catching
+at the CLI layer and mapping to appropriate exit codes.
+"""
+
+
+class LdapcError(Exception):
+    """Base exception for ldapc.
+
+    All ldapc-specific exceptions inherit from this class so the CLI
+    entry point can catch them uniformly and map to exit codes.
+    """
+
+
+class ConfigError(LdapcError):
+    """Configuration-related errors.
+
+    Raised when the configuration file is missing, contains invalid YAML,
+    or required fields are absent. Maps to exit code 2.
+    """
+
+
+class ConnectionError(LdapcError):
+    """LDAP connection errors.
+
+    Raised when the LDAP server is unreachable, the connection times out,
+    or TLS certificate verification fails. Maps to exit code 1.
+    """
+
+
+class AuthenticationError(LdapcError):
+    """LDAP bind/authentication errors.
+
+    Raised when the LDAP server rejects the bind credentials.
+    Maps to exit code 1.
+    """