dotseal 0.3.1

Git-friendly encrypted .env files with cleartext keys and sealed values (SOPS-inspired structural encryption).

dotseal

Git-friendly encrypted .env files with cleartext keys and sealed values.

  DEBUG=false
- API_KEY=ENC[AES_GCM,data:c2VjcmV0...]
+ API_KEY=ENC[AES_GCM,data:b3RoZXI=]
  DATABASE_URL=ENC[AES_GCM,data:Zm9vYmFy...]

DEBUG is left unencrypted using --plain-key — safe for non-sensitive values.

Installation

pip install dotseal  # or: uv add dotseal

Requires Python 3.9+.

Quickstart

# 1) Generate a local key (saved to .dotseal.key and gitignored)
dotseal init

# 2) Encrypt .env -> .env.enc (commit .env.enc only)
dotseal encrypt

# 3) Decrypt when needed
dotseal decrypt

Runtime load (no cleartext file required):

from dotseal import load_env

load_env()  # reads .env.enc and injects decrypted values into os.environ

What gets committed?

File	Commit it?	Why
.env.enc	Yes	Encrypted values with reviewable keys
.env	No	Cleartext secrets
.dotseal.key	Never	Symmetric master key
.dotseal.prv	Never	Asymmetric private key
dsk-pub-...	Yes	Asymmetric public keys are safe to share

Documentation

Use the docs as the source of truth for all details:

• Documentation index
• Usage and CLI
• Key management and rotation
• Asymmetric mode — not sure which mode to use? Start symmetric; switch when you need team sharing or revocation.
• CI/CD
• On-disk file format
• Editor integration

Security

• Selective encryption (--plain-key, --plain-key-regex) leaves chosen values in cleartext in .env.enc and git history; use only for non-secrets.
• AES-256-GCM authenticated encryption with per-value nonces.
• Variable names are bound as AAD, so ciphertext cannot be swapped across keys.
• Integrity is per value — review .env.enc changes like code changes.

Report vulnerabilities privately via SECURITY.md.

Contributing

See CONTRIBUTING.md.

License

MIT