kilit 0.1.0

Encrypted secrets management for Python, inspired by Rails credentials

Kilit 🔐

Encrypted secrets management for Python, inspired by Rails credentials.

Store API keys, database passwords, and sensitive config in version control safely.

Features

• 🔒 AES-256-GCM encryption with Scrypt KDF
• 📝 Edit secrets in your editor with auto-encryption
• 🔑 Multiple master key sources (file, env var, CLI)
• 📦 JSON and YAML support
• 🔄 Key rotation
• 🧵 Thread-safe runtime API
• 🌍 Cross-platform

Installation

pip install kilit
pip install kilit[yaml]  # With YAML support

Quick Start

# Initialize
kilit init

# Edit secrets
kilit edit

{
  "database": {"host": "localhost", "password": "secret123"},
  "api": {"key": "sk_live_abc123"}
}

# Use in your app
from kilit import Credentials

creds = Credentials("config/credentials.json.enc")
db_password = creds.get("database.password")
api_key = creds.require("api.key")  # Raises if missing

CLI Commands

kilit init                        # Initialize
kilit init --format yaml          # Use YAML
kilit init --print-master-key     # Print key for CI/CD

kilit edit                        # Edit in $EDITOR
kilit show                        # Display secrets
kilit show --redact               # Show structure only

eval $(kilit export)              # Export as env vars
kilit export --prefix MYAPP_      # With prefix

kilit rotate --write-new-master-key config/master.key  # Rotate key

Runtime API

from kilit import Credentials

creds = Credentials("config/credentials.json.enc")

# Dotted path access
db_host = creds.get("database.host")
timeout = creds.get("api.timeout", 30)  # With default
secret = creds.require("api.key")       # Raises if missing

# Reload
creds.reload()

Thread-safe for concurrent access.

Master Key Management

Priority: CLI arg > KILIT_MASTER_KEY env var > --master-key-path > config/master.key

Development:

echo "config/master.key" >> .gitignore

Production:

export KILIT_MASTER_KEY="<your-key>"

CI/CD:

env:
  KILIT_MASTER_KEY: ${{ secrets.KILIT_MASTER_KEY }}
run: eval $(kilit export) && python app.py

Security

• Encryption: AES-256-GCM with Scrypt KDF
• Salt: Unique per file (forward secrecy)
• Authentication: Tampering detection via GCM

Protection: Encrypted files safe in git. Secrets protected without master key. Scrypt makes brute-force expensive.

Master key: Single point of trust. Store securely (password manager, vault, env vars). Rotate if compromised.

Runtime: Secrets exist in memory during use. Follow secure coding practices.

Permissions: Unix systems auto-set 0600 on master key files.

Configuration

Scrypt (affects NEW encryptions only):

export KILIT_SCRYPT_N=32768  # CPU/memory cost (default: 16384)
export KILIT_SCRYPT_R=8      # Block size (default: 8)
export KILIT_SCRYPT_P=1      # Parallelization (default: 1)

Format: Auto-detected from extension (.json, .yaml, .yml). Override: --format yaml

Examples

See examples/ for Django, Flask, and FastAPI integration.

FAQ

Why not env vars? Lack structure, encryption at rest, easy to expose. Kilit provides both.

Lost master key? No recovery by design. Store in multiple secure locations.

Multiple files? Yes: Credentials("config/prod.json.enc")

Development

git clone https://github.com/erhan/kilit.git
cd kilit
uv venv && source .venv/bin/activate
uv pip install -e ".[dev,yaml]"

uv run pytest --cov=kilit
uv run ruff check .

Coverage: Goal 85%+, CI enforces 60% minimum.

Tasks

• Increase test coverage to 85%+
• Add more integration tests
• Improve CLI test coverage

Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Run tests: pytest --cov=kilit
6. Lint code: ruff check . && ruff format .
7. Commit: git commit -m 'Add amazing feature'
8. Push: git push origin feature/amazing-feature
9. Open a Pull Request

Credits

Inspired by Rails credentials. Built with cryptography and typer.

Special thanks to Kiro AI. 🤖✨

License

Copyright (c) 2026 Erhan Büte
Licensed under the MIT License.