# credentials

`utils.credentials`

Secure credential management module with enhanced masked password input.

This module provides secure credential storage and retrieval using the system’s secure credential store (Keychain on macOS, Credential Manager on Windows, SecretService/KWallet on Linux) with improved error handling and fallbacks.

It includes enhanced password input with masked characters for better usability when pasting from password managers, while still maintaining security.

## Classes

| Name | Description |
|----|----|
| [CredentialManager](#nova_fde.utils.credentials.CredentialManager) | Secure credential management system with enhanced password input. |

### CredentialManager

``` python
utils.credentials.CredentialManager(
    self,
    service_name='nova_fde',
    username=None,
    console=None,
)
```

Secure credential management system with enhanced password input.

This class provides secure storage and retrieval of credentials using the system’s secure credential store, with graceful fallbacks for errors and enhanced password input with masked characters.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| service_name | str | Name of the service for credential storage. | `'nova_fde'` |
| username | Optional\[str\] | Default username for the service. | `None` |
| console | Optional\[Console\] | Rich console for output. | `None` |

#### Notes

Credentials are stored in the system’s secure credential store: - macOS: Keychain - Windows: Credential Manager - Linux: SecretService/KWallet

#### Methods

| Name | Description |
|----|----|
| [clear_credentials](#nova_fde.utils.credentials.CredentialManager.clear_credentials) | Clear stored credentials from all storage backends. |
| [ensure_credentials_in_environment](#nova_fde.utils.credentials.CredentialManager.ensure_credentials_in_environment) | Ensure credentials are available in environment variables. |
| [get_credentials](#nova_fde.utils.credentials.CredentialManager.get_credentials) | Get credentials from secure storage. |
| [get_credentials_with_fallback](#nova_fde.utils.credentials.CredentialManager.get_credentials_with_fallback) | Get credentials with fallback to manual entry. |
| [store_credentials](#nova_fde.utils.credentials.CredentialManager.store_credentials) | Store credentials in secure storage. |
| [validate_connection](#nova_fde.utils.credentials.CredentialManager.validate_connection) | Validate credentials by testing the database connection. |

##### clear_credentials

``` python
utils.credentials.CredentialManager.clear_credentials()
```

Clear stored credentials from all storage backends.

##### ensure_credentials_in_environment

``` python
utils.credentials.CredentialManager.ensure_credentials_in_environment(
    verbose=False,
    use_masked_input=True,
)
```

Ensure credentials are available in environment variables.

This method retrieves credentials using the fallback mechanism and sets them as environment variables for use by other components.

###### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| verbose | bool | Whether to print additional information (default: False). | `False` |
| use_masked_input | bool | Whether to use masked password input (default: True). | `True` |

##### get_credentials

``` python
utils.credentials.CredentialManager.get_credentials(
    prompt_if_missing=True,
    verbose=False,
)
```

Get credentials from secure storage.

###### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| prompt_if_missing | bool | Whether to prompt for credentials if not found (default: True). | `True` |
| verbose | bool | Whether to print additional information (default: False). | `False` |

###### Returns

| Name | Type | Description |
|----|----|----|
|  | Tuple\[Optional\[str\], Optional\[str\]\] | Username and password tuple. |

##### get_credentials_with_fallback

``` python
utils.credentials.CredentialManager.get_credentials_with_fallback(
    verbose=False,
    use_masked_input=True,
)
```

Get credentials with fallback to manual entry.

This method tries all storage backends first, but falls back to manual entry if retrieval fails. Unlike get_credentials, this method always returns valid credentials or raises an exception.

###### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| verbose | bool | Whether to print additional information (default: False). | `False` |
| use_masked_input | bool | Whether to use masked password input (default: True). | `True` |

###### Returns

| Name | Type | Description |
|----|----|----|
|  | tuple\[str, str\] | Username and password tuple, guaranteed to be non-None. |

###### Raises

| Name | Type       | Description                        |
|------|------------|------------------------------------|
|      | ValueError | If credentials cannot be obtained. |

##### store_credentials

``` python
utils.credentials.CredentialManager.store_credentials(username, password)
```

Store credentials in secure storage.

###### Parameters

| Name     | Type | Description        | Default    |
|----------|------|--------------------|------------|
| username | str  | Username to store. | *required* |
| password | str  | Password to store. | *required* |

###### Raises

| Name | Type | Description |
|----|----|----|
|  | RuntimeError | If keyring is not available or credentials could not be stored. |

##### validate_connection

``` python
utils.credentials.CredentialManager.validate_connection(
    connection_func,
    max_attempts=3,
    verbose=False,
)
```

Validate credentials by testing the database connection.

###### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| connection_func | callable | Function that attempts to connect to the database using credentials. Should return True for success, False for failure. | *required* |
| max_attempts | int | Maximum number of connection attempts, by default 3 | `3` |
| verbose | bool | Whether to print additional information, by default False | `False` |

###### Returns

| Name | Type | Description                                    |
|------|------|------------------------------------------------|
|      | bool | True if credentials are valid, False otherwise |