dotseal 0.3.0

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.

dotseal encrypts only variable values, so you can safely commit .env.enc, review diffs, and keep secrets out of git history.

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

Installation

pip install dotseal

Requires Python 3.9+. Using uv? uv add dotseal.

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

Not sure which mode to use?

• Solo or small trusted setup: start with symmetric mode (dotseal init + dotseal encrypt).
• Team sharing without distributing one shared secret: use asymmetric mode.
• If you are unsure, start symmetric and switch later when sharing/revocation needs grow.
• Details: Asymmetric mode, Key management.

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
• CI/CD and deployment
• On-disk file format
• Editor integration

Security

• 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).
• Selective encryption (--plain-key, --plain-key-regex) leaves chosen values readable in the committed file and in git history; use only for non-secrets.

Report vulnerabilities privately via SECURITY.md.

Contributing

See CONTRIBUTING.md.

License

MIT