# 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

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

## Quick Start

```bash
# Initialize
kilit init

# Edit secrets
kilit edit
```

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

```python
# 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

```bash
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

```python
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:**
```bash
echo "config/master.key" >> .gitignore
```

**Production:**
```bash
export KILIT_MASTER_KEY="<your-key>"
```

**CI/CD:**
```yaml
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):**
```bash
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/](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

```bash
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](https://cryptography.io/) and [typer](https://typer.tiangolo.com/).

Special thanks to Kiro AI. 🤖✨

## License

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