Metadata-Version: 2.4
Name: django-root-secret
Version: 0.2.0
Summary: Django package for managing a single root encryption key and decrypting embedded secrets.
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: Django>=5.1
Dynamic: license-file

# django-root-secret

[![Tests](https://github.com/efe/django-root-secret/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/efe/django-root-secret/actions/workflows/tests.yml)

`django-root-secret` is a Django package for managing one root encryption key per environment and decrypting encrypted literals at runtime.

`django-root-secret` reduces the number of plaintext secrets you need to manage and tries to minimize the number of environment variables your project depends on. Large `.env` files are a common source of configuration errors because variables can be missing, misnamed, outdated, or inconsistent across environments. This package keeps the env file minimal by storing only `ROOT_ENCRYPTION_KEY` there and encrypting the rest.

## Installation

Install the package:

```bash
pip install django-root-secret
```

Add the app to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...,
    "django_root_secret",
]
```

## Commands

Generate a root key file:

```bash
python manage.py generate_root_encryption_key --env development
```

This creates `development.env` in the current working directory with only:

```dotenv
# This file must only contain ROOT_ENCRYPTION_KEY.
# Encrypt every other secret with this key and keep the file private.
ROOT_ENCRYPTION_KEY=...
```

If `development.env` is not already ignored by Git, the command also adds it to `.gitignore`.

Encrypt a plaintext secret using that file and bring up a prompt to paste the secret:

```bash
python manage.py encrypt_secret --env development
# Value to encrypt: [hidden input]
```

At runtime, make `ROOT_ENCRYPTION_KEY` available through your environment or deployment secret manager:

```bash
export ROOT_ENCRYPTION_KEY="..."
```

Then use the encrypted output in code:

```python
from django_root_secret import get_secret

DATABASE_PASSWORD = get_secret("gAAAAAB...")
```

## Note

This package started as an internal tool at [Hipo](https://hipolabs.com), and it brings back memories of a team I still appreciate deeply. 🦛
