SafeConfigAlpha 1.0.0

Secure API key and configuration management for Python developers

SafeConfig

Secure API key and configuration management for Python developers.

---

SafeConfig solves the configuration management problem once and for all:

• Multi-source loading — .env, JSON, YAML, and OS environment with priority merging
• AES-256-GCM encryption — protect sensitive values at rest with one command
• Multi-environment — development / staging / production out of the box
• Required-key validation — fail fast at startup, not at runtime
• CLI tool — safeconfig init, set, get, encrypt, doctor
• Source-code scanner — detect accidentally committed secrets
• Fully typed — complete type hints, ships a py.typed marker
• Zero magic — explicit, auditable, and predictable

---

Table of Contents

• Installation
• Quick Start
• Configuration Sources
• Encryption
• Multi-Environment
• CLI Reference
• API Reference
• Publishing to PyPI
• Contributing

---

Installation

pip install safeconfig

For development (includes linting, type checking, and test tools):

git clone https://github.com/yourusername/safeconfig
cd safeconfig
pip install -e ".[dev]"
pre-commit install

Dependencies: cryptography, python-dotenv, pyyaml, click, rich, platformdirs

---

Quick Start

1. Initialise your project

safeconfig init

This creates a .env file and generates a master encryption key. Copy the key to a safe location (password manager, secret vault).

🔑  Master Key
────────────────────────────────────────
Your new master key

abc123XYZ...  ← store this securely!
────────────────────────────────────────
✔  Created .env

2. Add your secrets

safeconfig set DATABASE_URL postgres://localhost/mydb
safeconfig set API_KEY sk-prod-very-secret --encrypt   # stored as AES-256 ciphertext

3. Use in your application

from safeconfig import SafeConfig

config = SafeConfig(
    environment="production",
    required_keys=["DATABASE_URL", "API_KEY"],
)
config.load()

db_url  = config.get("DATABASE_URL")
api_key = config.get("API_KEY", decrypt=True)   # transparent decryption
workers = config.get_int("MAX_WORKERS", default=4)
debug   = config.get_bool("DEBUG", default=False)
hosts   = config.get_list("ALLOWED_HOSTS")

4. Diagnose problems

safeconfig doctor

┌────────────────────────────────────────┬──────────┬───────────────────────────────┐
│ Check                                  │ Status   │ Detail                        │
├────────────────────────────────────────┼──────────┼───────────────────────────────┤
│ Master key (env var)                   │ ✔ OK     │ Valid key found in environment │
│ .env file (.env)                       │ ✔ OK     │ File found                    │
│ .gitignore                             │ ✔ OK     │ .env is ignored               │
│ Source code scan                       │ ✔ OK     │ No exposed secrets in 12 file  │
└────────────────────────────────────────┴──────────┴───────────────────────────────┘
All checks passed! Your configuration looks healthy.

---

Configuration Sources

SafeConfig merges configuration from multiple sources. Priority order (highest → lowest):

1. OS environment variables
2. Custom loaders (added via add_loader(), in reverse order of registration)
3. Environment-specific .env file (e.g. .env.production)
4. Base .env file

from safeconfig import SafeConfig
from safeconfig.core.loaders import DotEnvLoader, JsonLoader, YamlLoader

config = SafeConfig()
config.add_json("config/database.json")
config.add_yaml("config/features.yaml")
config.add_loader(DotEnvLoader(".env.local"))
config.load()

.env file

# .env
DATABASE_URL=postgres://localhost/mydb
API_KEY=enc:AQID...   # encrypted blob — auto-decrypted on get()
DEBUG=true
MAX_WORKERS=4
ALLOWED_HOSTS=localhost,127.0.0.1

JSON (nested keys are flattened with .)

{
  "redis": { "host": "localhost", "port": 6379 },
  "s3":    { "bucket": "my-bucket", "region": "us-east-1" }
}

config.get("redis.host")    # "localhost"
config.get_int("redis.port") # 6379

YAML (same flattening rules)

redis:
  host: localhost
  port: 6379
feature_flags:
  beta_signup: true

---

Encryption

SafeConfig uses AES-256-GCM (authenticated encryption) with PBKDF2-HMAC-SHA256 key derivation. Each encrypted value carries its own random salt and nonce, so encrypting the same plaintext twice always produces different ciphertexts.

Generate a master key

safeconfig init          # generates a key and writes it to .env
# or:
python -c "from safeconfig import SafeConfig; print(SafeConfig.generate_master_key())"

Store the key in SAFECONFIG_MASTER_KEY (env var or CI/CD secret). Never commit it.

Encrypt from the CLI

# Encrypt an existing plaintext value in .env (in place):
safeconfig encrypt SECRET_API_KEY

# Set a new value as encrypted:
safeconfig set STRIPE_SECRET sk_live_... --encrypt

Encrypt from Python

config = SafeConfig(master_key="your-key")
config.load()

blob = config.encrypt("PLAINTEXT_KEY")      # updates the in-memory store
value = config.get("PLAINTEXT_KEY", decrypt=True)

Encrypted blob format

<version:1B> <salt:16B> <nonce:12B> <ciphertext+tag:NB>

encoded as URL-safe base64. Values stored in .env have an enc: prefix so SafeConfig auto-decrypts them on get().

---

Multi-Environment

# Reads APP_ENV from the environment, defaulting to "development"
config = SafeConfig(environment="production", config_dir="config/")
config.load()

SafeConfig automatically loads .env and .env.production. The environment-specific file takes precedence.

Supported environments: development, staging, production, test, local.

---

CLI Reference

Usage: safeconfig [OPTIONS] COMMAND [ARGS]...

Options:
  --env-file TEXT  Path to the .env file  [default: .env]
  -v, --verbose    Enable verbose logging
  --help           Show this message and exit.

Commands:
  init     Scaffold a .env file and generate a master encryption key.
  set      Set KEY to VALUE in the .env file.
  get      Print the value of KEY from the .env file.
  encrypt  Encrypt an existing plaintext value in the .env file.
  doctor   Diagnose common configuration issues.

safeconfig init

safeconfig init
safeconfig init -k DATABASE_URL -k API_KEY   # pre-populate template keys
safeconfig init --force                       # overwrite existing .env

safeconfig set

safeconfig set DATABASE_URL postgres://localhost/mydb
safeconfig set SECRET sk_live_abc123 --encrypt
safeconfig --env-file .env.production set LOG_LEVEL WARNING

safeconfig get

safeconfig get DATABASE_URL
safeconfig get SECRET           # auto-decrypts enc: values
safeconfig get SECRET --raw     # print encrypted blob without decrypting

safeconfig encrypt

safeconfig encrypt SECRET_API_KEY          # encrypt in-place in .env
safeconfig encrypt SECRET --no-in-place   # print blob, don't modify file

safeconfig doctor

safeconfig doctor
safeconfig doctor --scan-dir src/    # scan specific directory for exposed secrets

---

API Reference

SafeConfig

SafeConfig(
    environment="development",     # or read from APP_ENV
    required_keys=["DB_URL"],      # raise MissingRequiredKeyError if absent
    config_dir=".",                # where to look for .env files
    master_key=None,               # or read from SAFECONFIG_MASTER_KEY
    auto_load_env=True,            # auto-register .env and .env.<environment>
    strict=False,                  # raise KeyNotFoundError instead of returning None
)

Method	Description
.load(force=False)	Load all sources and validate required keys
.reload()	Force a full reload
.get(key, default, decrypt=False)	Get a value
.require(key, decrypt=False)	Get a value, raise if absent
.get_int(key, default)	Get as integer
.get_bool(key, default)	Get as boolean
.get_list(key, default, separator=",")	Get as list
.set(key, value, encrypt=False)	Set in-memory value
.encrypt(key)	Encrypt in-place in the in-memory store
.add_loader(loader)	Register a custom loader
.add_json(path)	Add a JSON source
.add_yaml(path)	Add a YAML source
.all()	Return all loaded key-value pairs
.keys()	Return sorted list of keys
SafeConfig.generate_master_key()	Generate a new master key

Exceptions

Exception	Raised when
ConfigurationError	Base class for all library errors
KeyNotFoundError	Key not found (in strict mode or via .require())
MissingRequiredKeyError	Required key absent after load
EncryptionError	Encryption failed
DecryptionError	Decryption failed (wrong key or corrupted value)
InvalidEnvironmentError	Unknown environment name
MasterKeyError	Master key missing or malformed
ExposedKeyWarning	Hard-coded secret detected in source (warning, not error)

---

Publishing to PyPI

Prerequisites

1. Register an account at pypi.org
2. Install build tools: pip install build twine

Manual publish

# 1. Bump version in pyproject.toml
# 2. Build distributions
python -m build

# 3. Upload to TestPyPI first (recommended)
twine upload --repository testpypi dist/*

# 4. Test the installation
pip install --index-url https://test.pypi.org/simple/ safeconfig

# 5. Upload to PyPI
twine upload dist/*

Automated publish via GitHub Actions

The included CI workflow publishes automatically when you push a version tag:

git tag v1.0.0
git push origin v1.0.0

Configure PyPI Trusted Publishing in your PyPI project settings to avoid storing API tokens in GitHub Secrets.

---

Contributing

# Clone and set up
git clone https://github.com/yourusername/safeconfig
cd safeconfig
pip install -e ".[dev]"
pre-commit install

# Run tests
pytest

# Run type checker
mypy src/safeconfig/

# Run linter
ruff check src/ tests/

PRs are welcome! Please open an issue first to discuss substantial changes.

---

License

MIT © 2024 Your Name