Secure Credential Management

Treasury Analytics Core provides multiple secure options for managing database credentials, now enhanced with centralized settings and password expiration tracking.

Using System Keyring

A secure method is to use your system’s secure credential store:

  • macOS: Keychain
  • Windows: Credential Manager
  • Linux: SecretService/KWallet

Setting Up Credentials in Keyring

You can set up credentials using the included setup tools:

# Interactive setup helper
python -m nova_fde.utils.setup_helper

# OR dedicated configuration tool
python -m nova_fde.scripts.configure_db --keyring-only

Using Keyring in Your Code

Once credentials are stored in your system keyring, you can use them in code:

from nova_fde import FinanceDataEngine
from nova_fde.utils import setup_logging

# Set up logging
logger, console = setup_logging()

# Initialize with credentials from keyring
engine = FinanceDataEngine(
    console=console,
    use_keyring=True,
    keyring_service="nova_fde"
)

Using Private Credential Directories

For environments where keyring isn’t available, you can store credentials in a private directory:

from nova_fde import FinanceDataEngine

# Initialize with credentials from a private directory
engine = FinanceDataEngine(
    credential_path="C:/Users/username/private/credentials"
)

To set up a credential file in a private directory:

# Create a credentials file in a private directory
python -m nova_fde.scripts.configure_db --path /path/to/private/directory

Using Settings Factory

For more advanced configuration, use the settings factory:

from nova_fde import FinanceDataEngine
from nova_fde.config.settings_factory import SettingsFactory

# Create settings from keyring
settings = SettingsFactory.from_keyring()

# Or from a credential path
settings = SettingsFactory.from_credential_path("/path/to/credentials")

# Or with global database settings
from nova_fde.core.engine_factory import GlobalSettings
global_settings = GlobalSettings()
db_settings = global_settings.get_db_settings()

# Initialize engine with settings
engine = FinanceDataEngine(settings=settings)

Password Expiration Management

Treasury Analytics Core now includes password expiration tracking to ensure database passwords are rotated regularly:

Recording a Password Update

When you update your database password, record it to start tracking expiration:

python -m nova_fde.scripts.manage_settings --update-password

Checking Password Expiration

Check the status of your password expiration:

python -m nova_fde.scripts.manage_settings --check

Creating a Calendar Reminder

Create a calendar reminder file for password rotation:

python -m nova_fde.scripts.manage_settings --create-reminder

For more information about password management, see the Global Settings & Password Management documentation.

Direct Credential Management

You can also directly use the CredentialManager class for more control:

from nova_fde.utils.credentials import CredentialManager

# Create credential manager
cred_mgr = CredentialManager(service_name="nova_fde")

# Store credentials
cred_mgr.store_credentials("username", "password")

# Retrieve credentials
username, password = cred_mgr.get_credentials()

# Clear credentials
cred_mgr.clear_credentials()

Command-Line Configuration

The configure_db script provides a command-line interface for setting up database credentials:

# Store credentials in keyring and create .env file
python -m nova_fde.scripts.configure_db --path ./my_project

# Store credentials in keyring only
python -m nova_fde.scripts.configure_db --keyring-only

# Specify a custom keyring service name
python -m nova_fde.scripts.configure_db --service my_service_name

Credential Validation

The CredentialManager provides methods to validate credentials:

from nova_fde.utils.credentials import CredentialManager
from sqlalchemy import create_engine, text

# Create credential manager
cred_mgr = CredentialManager(service_name="nova_fde")

# Define a function to test the connection
def test_connection(username, password):
    try:
        # Create a connection string
        conn_str = f"postgresql://{username}:{password}@your_host:5432/your_db"
        
        # Create engine and test connection
        engine = create_engine(conn_str)
        with engine.connect() as conn:
            result = conn.execute(text("SELECT 1")).fetchone()
            return result[0] == 1
    except Exception:
        return False

# Validate credentials with connection test
valid = cred_mgr.validate_connection(
    connection_func=test_connection,
    max_attempts=3,
    verbose=True
)

if valid:
    print("Connection successful!")
else:
    print("Could not establish connection with provided credentials")

First-Time Setup

For new users, the setup helper provides a guided setup experience:

python -m nova_fde.utils.setup_helper

This interactive tool will:

  1. Ask about credential storage preferences
  2. Collect database connection information
  3. Store credentials securely in the system keyring
  4. Optionally create a minimal .env file without the password
  5. Offer to set up global settings for database configuration

Integration with Global Settings

When using global settings, you only need to store username and password credentials - other database connection details come from the centralized configuration:

  1. First set up your global settings:

    python -m nova_fde.scripts.manage_settings --create \
  --db-host=your-server.example.com \
  --db-port=5432 \
  --db-name=your_database

  2. Then store just your credentials:

    python -m nova_fde.scripts.configure_db --keyring-only

  3. Use both in your code:

    engine = EngineFactory.create_with_auto_auth(
    project_root="./my_project",
    check_password_expiry=True
)

This approach provides the best security and maintainability by separating database connection details from credentials.