ldap-cli 0.2.0__py3-none-any.whl

.kiro/specs/ldap-cli/design.md

@@ -0,0 +1,386 @@
+# Design Document: ldap-cli
+
+## Overview
+
+`ldapc` is a Python CLI tool for querying LDAP directories. It provides user and group search capabilities with persistent configuration and secure credential storage via the OS keychain.
+
+The tool follows the same project conventions as `cftcli` and `identity-provider`: a single package with module-per-command structure, `pyproject.toml` for build configuration, hatchling as the build backend, and pytest for testing.
+
+### Key Design Decisions
+
+1. **`ldap3` over `python-ldap`**: The `ldap3` library is a pure-Python RFC 4510 conforming LDAP client. Unlike `python-ldap`, it requires no C compiler or OpenLDAP development headers, making installation trivial across platforms.
+
+2. **`keyring` for credential storage**: The `keyring` library provides a unified API across macOS Keychain, Windows Credential Manager, and Linux Secret Service (via D-Bus). This avoids platform-specific code.
+
+3. **`argparse` for CLI parsing**: Standard library, no extra dependency. Matches the pattern used in `cftcli`.
+
+4. **`pyyaml` for configuration**: Already used across the workspace projects. Lightweight and well-understood.
+
+5. **Dataclass-based configuration**: Following the pattern in `identity-provider`, configuration is modeled as a dataclass for type safety and easy serialization.
+
+## Architecture
+
+```mermaid
+graph TD
+    A[ldapc CLI Entry Point] --> B{Argument Parser}
+    B -->|--configure| C[Configure Command]
+    B -->|--user| D[User Search Command]
+    B -->|--group| E[Group Search Command]
+    B -->|--version| F[Version Display]
+    B -->|--help / no args| G[Help Display]
+
+    C --> H[Config Writer]
+    C --> I[Keyring Store]
+
+    D --> J[Config Loader]
+    D --> K[LDAP Client]
+    D --> L[Result Formatter]
+
+    E --> J
+    E --> K
+    E --> L
+
+    J --> M[~/.ldapc/config.yaml]
+    I --> N[OS Keychain]
+    K --> O[LDAP Server]
+```
+
+### Layer Separation
+
+| Layer | Responsibility | Modules |
+|-------|---------------|---------|
+| CLI | Argument parsing, entry point, exit codes | `__init__.py`, `cli.py` |
+| Config | Read/write YAML config, keyring access | `config.py` |
+| LDAP | Connection management, search queries | `ldap_client.py` |
+| Formatting | Output rendering (text, JSON) | `formatter.py` |
+
+## Components and Interfaces
+
+### CLI Module (`ldapc/cli.py`)
+
+```python
+def main() -> None:
+    """Entry point registered as console script `ldapc`."""
+    ...
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser with all flags."""
+    ...
+```
+
+### Config Module (`ldapc/config.py`)
+
+```python
+@dataclass
+class LdapcConfig:
+    """Configuration object for ldapc."""
+    host: str
+    username: str
+    base_dn: str = ""
+
+def load_config(config_path: Path | None = None) -> LdapcConfig:
+    """Load configuration from ~/.ldapc/config.yaml.
+
+    Raises:
+        ConfigError: If the file is missing or contains invalid YAML.
+    """
+    ...
+
+def save_config(config: LdapcConfig, config_path: Path | None = None) -> None:
+    """Serialize config to ~/.ldapc/config.yaml with 0600 permissions."""
+    ...
+
+def config_to_yaml(config: LdapcConfig) -> str:
+    """Serialize a config object to a YAML string."""
+    ...
+
+def yaml_to_config(yaml_str: str) -> LdapcConfig:
+    """Parse a YAML string into a config object.
+
+    Raises:
+        ConfigError: If the YAML is invalid or missing required fields.
+    """
+    ...
+
+def store_password(username: str, password: str) -> None:
+    """Store password in OS keychain under service 'ldapc'."""
+    ...
+
+def retrieve_password(username: str) -> str:
+    """Retrieve password from OS keychain.
+
+    Raises:
+        ConfigError: If no password is stored for the account.
+    """
+    ...
+```
+
+### LDAP Client Module (`ldapc/ldap_client.py`)
+
+```python
+@dataclass
+class LdapEntry:
+    """A single LDAP directory entry."""
+    dn: str
+    attributes: dict[str, list[str]]
+
+class LdapClient:
+    """Manages LDAP connections and searches."""
+
+    def __init__(self, host: str, username: str, password: str, timeout: int = 10) -> None:
+        ...
+
+    def search_users(self, search_term: str, base_dn: str) -> list[LdapEntry]:
+        """Search for user entries matching cn or uid."""
+        ...
+
+    def search_groups(self, search_term: str, base_dn: str) -> list[LdapEntry]:
+        """Search for group entries matching cn."""
+        ...
+
+    def close(self) -> None:
+        """Unbind and close the LDAP connection."""
+        ...
+```
+
+### Formatter Module (`ldapc/formatter.py`)
+
+```python
+def format_user_entries(entries: list[LdapEntry]) -> str:
+    """Format user entries as aligned key-value text."""
+    ...
+
+def format_group_entries(entries: list[LdapEntry]) -> str:
+    """Format group entries as aligned key-value text."""
+    ...
+
+def format_entries_json(entries: list[LdapEntry]) -> str:
+    """Format entries as a JSON string."""
+    ...
+
+def build_user_filter(search_term: str) -> str:
+    """Construct an LDAP filter for user search (cn and uid)."""
+    ...
+
+def build_group_filter(search_term: str) -> str:
+    """Construct an LDAP filter for group search (cn)."""
+    ...
+```
+
+### Exceptions (`ldapc/exceptions.py`)
+
+```python
+class LdapcError(Exception):
+    """Base exception for ldapc."""
+    ...
+
+class ConfigError(LdapcError):
+    """Configuration-related errors (exit code 2)."""
+    ...
+
+class ConnectionError(LdapcError):
+    """LDAP connection errors (exit code 1)."""
+    ...
+
+class AuthenticationError(LdapcError):
+    """LDAP bind/authentication errors (exit code 1)."""
+    ...
+```
+
+## Data Models
+
+### Configuration File (`~/.ldapc/config.yaml`)
+
+```yaml
+host: ldaps://ldap.example.com:636
+username: cn=admin,dc=example,dc=com
+base_dn: dc=example,dc=com
+```
+
+### LdapcConfig Dataclass
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `host` | `str` | Yes | LDAP server URL (ldaps:// or ldap://) |
+| `username` | `str` | Yes | Bind DN for authentication |
+| `base_dn` | `str` | No | Base DN for searches (defaults to derived from host) |
+
+### LdapEntry Dataclass
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dn` | `str` | Distinguished name of the entry |
+| `attributes` | `dict[str, list[str]]` | Attribute name → list of values |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (including no results) |
+| 1 | Connection or authentication error |
+| 2 | Configuration error or invalid arguments |
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: Configuration round-trip
+
+*For any* valid `LdapcConfig` object containing arbitrary host and username strings, serializing it to YAML via `config_to_yaml` and then parsing it back via `yaml_to_config` SHALL produce an equivalent configuration object.
+
+**Validates: Requirements 2.4, 3.1, 3.3, 3.4**
+
+### Property 2: Invalid YAML produces a descriptive error
+
+*For any* string that is not valid YAML (or valid YAML missing required fields), calling `yaml_to_config` SHALL raise a `ConfigError` with a non-empty message describing the failure.
+
+**Validates: Requirements 3.2**
+
+### Property 3: Password is never written to disk
+
+*For any* valid configuration containing a password, after running the configuration save flow, the password string SHALL NOT appear in the contents of `~/.ldapc/config.yaml` or any other file in `~/.ldapc/`.
+
+**Validates: Requirements 4.4**
+
+### Property 4: User search filter construction
+
+*For any* non-empty search term string, `build_user_filter(search_term)` SHALL produce a valid LDAP filter that matches against both `cn` and `uid` attributes, and the search term SHALL appear in the resulting filter string.
+
+**Validates: Requirements 5.1**
+
+### Property 5: Group search filter construction
+
+*For any* non-empty search term string, `build_group_filter(search_term)` SHALL produce a valid LDAP filter that matches against the `cn` attribute, and the search term SHALL appear in the resulting filter string.
+
+**Validates: Requirements 6.1**
+
+### Property 6: Entry formatting contains all required fields
+
+*For any* `LdapEntry` with a non-empty `dn` and attributes containing `cn`, `mail`, and `memberOf` (for users) or `cn`, `description`, and `member` (for groups), the formatted output string SHALL contain the entry's DN and all specified attribute values.
+
+**Validates: Requirements 5.2, 6.2, 7.1**
+
+### Property 7: JSON output is valid and round-trips
+
+*For any* list of `LdapEntry` objects, `format_entries_json(entries)` SHALL produce a string that is valid JSON, and deserializing that JSON SHALL yield data equivalent to the original entries' DN and attributes.
+
+**Validates: Requirements 7.3**
+
+## Error Handling
+
+| Error Condition | User-Facing Message | Exit Code | Stream |
+|----------------|--------------------:|:---------:|--------|
+| Config file missing | `Configuration not found. Run 'ldapc --configure' to set up.` | 2 | stderr |
+| Config file invalid YAML | `Invalid configuration file: {details}` | 2 | stderr |
+| Keychain password missing | `No stored password. Run 'ldapc --configure' to set up.` | 2 | stderr |
+| Invalid arguments | argparse default error | 2 | stderr |
+| LDAP server unreachable | `Connection failed: unable to reach {host}` | 1 | stderr |
+| LDAP connection timeout | `Connection timed out after 10 seconds: {host}` | 1 | stderr |
+| TLS certificate error | `TLS certificate verification failed for {host}` | 1 | stderr |
+| Authentication failure | `Authentication failed: invalid credentials for {username}` | 1 | stderr |
+| No results found | `No results found for '{search_term}'` | 0 | stdout |
+
+### Error Handling Strategy
+
+- All exceptions inherit from `LdapcError` for consistent catching at the CLI layer.
+- The CLI `main()` function wraps command execution in a try/except that maps exception types to exit codes.
+- Error messages go to stderr; query results go to stdout.
+- LDAP connections are always closed in a `finally` block to prevent resource leaks.
+
+## Testing Strategy
+
+### Test Framework and Tools
+
+- **pytest** for test execution
+- **hypothesis** for property-based testing
+- **unittest.mock** for mocking LDAP connections and keyring
+- **pytest-cov** for coverage reporting
+
+### Property-Based Tests (hypothesis)
+
+Each correctness property maps to a single hypothesis test with minimum 100 iterations:
+
+| Property | Test File | Strategy |
+|----------|-----------|----------|
+| 1: Config round-trip | `tests/test_config_properties.py` | Generate random `LdapcConfig` objects via `@st.composite` |
+| 2: Invalid YAML error | `tests/test_config_properties.py` | Generate random non-YAML strings |
+| 3: Password not on disk | `tests/test_config_properties.py` | Generate random passwords, run save, grep files |
+| 4: User filter construction | `tests/test_search_properties.py` | Generate random search term strings |
+| 5: Group filter construction | `tests/test_search_properties.py` | Generate random search term strings |
+| 6: Entry formatting | `tests/test_formatter_properties.py` | Generate random `LdapEntry` objects |
+| 7: JSON round-trip | `tests/test_formatter_properties.py` | Generate random lists of `LdapEntry` objects |
+
+Each test is tagged with: `# Feature: ldap-cli, Property {N}: {title}`
+
+Configuration: `@settings(max_examples=100)`
+
+### Unit Tests (example-based)
+
+| Area | Test File | Coverage |
+|------|-----------|----------|
+| CLI argument parsing | `tests/test_cli.py` | --help, --version, no args, invalid args |
+| Configure flow | `tests/test_configure.py` | Prompts, directory creation, permissions |
+| Error scenarios | `tests/test_errors.py` | Connection failures, auth failures, timeouts |
+| Exit codes | `tests/test_exit_codes.py` | All exit code scenarios |
+| Output streams | `tests/test_output.py` | stderr for errors, stdout for results |
+
+### Integration Tests
+
+| Area | Test File | Coverage |
+|------|-----------|----------|
+| Keyring integration | `tests/test_keyring_integration.py` | Store/retrieve with mocked keyring backend |
+| LDAP connection lifecycle | `tests/test_ldap_integration.py` | Connect, search, unbind with mocked server |
+
+### Project Structure
+
+```
+ldapc/
+├── pyproject.toml
+├── CHANGELOG.md
+├── README.md
+├── LICENSE
+├── docs/
+│   └── README.md
+├── ldapc/
+│   ├── __init__.py
+│   ├── _version.py
+│   ├── cli.py
+│   ├── config.py
+│   ├── ldap_client.py
+│   ├── formatter.py
+│   └── exceptions.py
+└── tests/
+    ├── __init__.py
+    ├── conftest.py
+    ├── test_cli.py
+    ├── test_configure.py
+    ├── test_config_properties.py
+    ├── test_search_properties.py
+    ├── test_formatter_properties.py
+    ├── test_errors.py
+    ├── test_exit_codes.py
+    ├── test_output.py
+    ├── test_keyring_integration.py
+    └── test_ldap_integration.py
+```
+
+### Dependencies
+
+```toml
+[project]
+dependencies = [
+    "ldap3>=2.9,<3.0",
+    "keyring>=25.0,<26.0",
+    "pyyaml>=6.0,<7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-cov>=5.0,<6.0",
+    "hypothesis>=6.100,<7.0",
+    "ruff>=0.4,<1.0",
+    "mypy>=1.10,<2.0",
+    "bandit>=1.7,<2.0",
+]
+```

.kiro/specs/ldap-cli/requirements.md

@@ -0,0 +1,123 @@
+# Requirements Document
+
+## Introduction
+
+A Python CLI tool (`ldapc`) for querying LDAP directories. The tool provides a simple interface to search for users and groups, with persistent configuration stored locally and secure credential management via the OS keychain.
+
+## Glossary
+
+- **CLI**: The `ldapc` command-line interface application
+- **Configuration_Store**: The YAML configuration file located at `~/.ldapc/config.yaml`
+- **Keychain**: The operating system's native credential storage (macOS Keychain, Windows Credential Manager, or Linux Secret Service)
+- **LDAP_Server**: The remote LDAP directory server the CLI connects to
+- **Config_Parser**: The component that reads and writes `~/.ldapc/config.yaml`
+- **Config_Printer**: The component that serializes configuration objects back to YAML format
+- **Search_Result**: A structured object containing attributes returned from an LDAP query
+
+## Requirements
+
+### Requirement 1: CLI Entry Point
+
+**User Story:** As a developer, I want to invoke the LDAP CLI by typing `ldapc`, so that I can quickly query LDAP without remembering long commands.
+
+#### Acceptance Criteria
+
+1. THE CLI SHALL be invocable as `ldapc` from the shell after installation
+2. WHEN invoked without arguments, THE CLI SHALL display a help message showing available options and usage examples
+3. WHEN invoked with `--version`, THE CLI SHALL display the current version string
+4. WHEN invoked with `--help`, THE CLI SHALL display the full help text including all supported flags
+
+### Requirement 2: Interactive Configuration
+
+**User Story:** As a developer, I want to configure the LDAP host and credentials interactively, so that I do not have to provide them on every invocation.
+
+#### Acceptance Criteria
+
+1. WHEN invoked with `--configure`, THE CLI SHALL prompt the user for the LDAP host URL
+2. WHEN invoked with `--configure`, THE CLI SHALL prompt the user for the bind username
+3. WHEN invoked with `--configure`, THE CLI SHALL prompt the user for the bind password
+4. WHEN the user completes the configuration prompts, THE Configuration_Store SHALL persist the host and username to `~/.ldapc/config.yaml`
+5. WHEN the user completes the configuration prompts, THE CLI SHALL store the password in the Keychain
+6. IF the `~/.ldapc/` directory does not exist, THEN THE CLI SHALL create it before writing the configuration file
+7. THE Configuration_Store SHALL set file permissions on `~/.ldapc/config.yaml` to owner-read-write only (0600)
+
+### Requirement 3: Configuration File Parsing
+
+**User Story:** As a developer, I want the CLI to reliably read and write its configuration file, so that my settings persist across sessions.
+
+#### Acceptance Criteria
+
+1. WHEN a valid `~/.ldapc/config.yaml` file exists, THE Config_Parser SHALL parse it into a configuration object containing host and username
+2. IF `~/.ldapc/config.yaml` contains invalid YAML, THEN THE Config_Parser SHALL return a descriptive error message indicating the parse failure
+3. THE Config_Printer SHALL format configuration objects back into valid YAML files
+4. FOR ALL valid configuration objects, parsing then printing then parsing SHALL produce an equivalent object (round-trip property)
+5. IF `~/.ldapc/config.yaml` does not exist, THEN THE CLI SHALL display an error instructing the user to run `ldapc --configure`
+
+### Requirement 4: Secure Credential Storage
+
+**User Story:** As a developer, I want my LDAP password stored securely in the OS keychain, so that it is not exposed in plain-text files.
+
+#### Acceptance Criteria
+
+1. WHEN storing credentials, THE CLI SHALL use the OS Keychain with service name `ldapc` and the configured username as the account identifier
+2. WHEN retrieving credentials for an LDAP connection, THE CLI SHALL read the password from the Keychain
+3. IF the Keychain does not contain a stored password for the configured account, THEN THE CLI SHALL display an error instructing the user to run `ldapc --configure`
+4. THE CLI SHALL NOT write the password to any file on disk
+
+### Requirement 5: Query by User
+
+**User Story:** As a developer, I want to search LDAP for a user by name, so that I can quickly look up user attributes.
+
+#### Acceptance Criteria
+
+1. WHEN invoked with `--user {searchuser}`, THE CLI SHALL query the LDAP_Server for entries matching the search term against common name and uid attributes
+2. WHEN the LDAP_Server returns matching user entries, THE CLI SHALL display each entry's distinguished name, common name, email, and group memberships in a readable format
+3. WHEN the LDAP_Server returns no matching user entries, THE CLI SHALL display a message indicating no results were found for the search term
+4. IF the LDAP_Server is unreachable, THEN THE CLI SHALL display a connection error message including the configured host
+5. IF the LDAP bind credentials are rejected, THEN THE CLI SHALL display an authentication error message
+
+### Requirement 6: Query by Group
+
+**User Story:** As a developer, I want to search LDAP for a group by name, so that I can see group membership details.
+
+#### Acceptance Criteria
+
+1. WHEN invoked with `--group {searchgroup}`, THE CLI SHALL query the LDAP_Server for group entries matching the search term against common name
+2. WHEN the LDAP_Server returns matching group entries, THE CLI SHALL display each group's distinguished name, common name, description, and member list in a readable format
+3. WHEN the LDAP_Server returns no matching group entries, THE CLI SHALL display a message indicating no results were found for the search term
+4. IF the LDAP_Server is unreachable, THEN THE CLI SHALL display a connection error message including the configured host
+5. IF the LDAP bind credentials are rejected, THEN THE CLI SHALL display an authentication error message
+
+### Requirement 7: Output Formatting
+
+**User Story:** As a developer, I want search results displayed in a clear, readable format, so that I can quickly find the information I need.
+
+#### Acceptance Criteria
+
+1. THE CLI SHALL display search results using aligned key-value formatting for single results
+2. WHEN multiple results are returned, THE CLI SHALL visually separate each entry with a delimiter
+3. WHEN the `--json` flag is provided, THE CLI SHALL output results as valid JSON to stdout
+4. THE CLI SHALL write error messages to stderr, keeping stdout reserved for query results
+
+### Requirement 8: Connection Management
+
+**User Story:** As a developer, I want the CLI to handle LDAP connections reliably, so that queries complete without leaving stale connections.
+
+#### Acceptance Criteria
+
+1. WHEN a query is initiated, THE CLI SHALL establish a TLS-secured connection to the LDAP_Server
+2. WHEN a query completes, THE CLI SHALL unbind and close the LDAP connection
+3. IF the connection times out after 10 seconds, THEN THE CLI SHALL display a timeout error and exit with a non-zero status code
+4. IF a TLS certificate verification fails, THEN THE CLI SHALL display a certificate error message
+
+### Requirement 9: Exit Codes
+
+**User Story:** As a developer, I want consistent exit codes, so that I can use `ldapc` in scripts and automation.
+
+#### Acceptance Criteria
+
+1. WHEN a query completes successfully, THE CLI SHALL exit with code 0
+2. WHEN a query returns no results, THE CLI SHALL exit with code 0
+3. IF a connection or authentication error occurs, THEN THE CLI SHALL exit with code 1
+4. IF a configuration error occurs, THEN THE CLI SHALL exit with code 2
+5. IF an invalid argument is provided, THEN THE CLI SHALL exit with code 2