Philosophy & Non-Goals

Design Philosophy

dotsecenv prioritizes usability. Security tools that frustrate developers don’t get used.

Philosophy	Implementation
UX-first	Simple commands, minimal config
UNIX philosophy	Do one thing well, be composable
Decentralized	GPG keys, no clouds required
Offline-first	Works without a network
Development focus	SDLC, not production
Append-only	Auditability, additive changes by default

Core Principles

Easy to use

Minimal configuration. Simple commands. Sensible defaults.

Easy to learn

Intuitive command names. Few flags to memorize. Help when you need it.

Easy to remember

When memory fails, man pages and descriptive errors guide you.

Opinionated but not restrictive

Strong defaults. Escape hatches when needed.

Why dotsecenv Exists

GPG does all the heavy lifting for encryption and web-of-trust. But using GPG directly requires:

• Generating keys (choosing algorithms, key sizes, expiration)
• Publishing keys, managing keyrings, handling trust
• Understanding encryption vs. signing
• Remembering complex commands with many flags

dotsecenv makes GPG easy.

You likely already have a GPG key—GitHub and GitLab require them for commit signature verification. dotsecenv builds on that existing premise.

---

UNIX Philosophy

dotsecenv follows the UNIX philosophy as articulated by Doug McIlroy:

“Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface.”

Applied to dotsecenv

Principle	Application
Do one thing well	Encrypt/decrypt secrets. That’s it.
Composable	Works with git, shell, other tools
Text streams	Secrets via stdin/stdout. JSON output with --json
No Swiss Army knife	Doesn’t try to do everything

Standing on Giants

Some problems are already solved well:

• GPG — Encryption and key management
• Git — Version control and distribution
• Shell — Environment variable loading

dotsecenv adds a minimal layer of usability and relies on these vetted, stable tools.

---

Why GPG and Not age?

age is a modern encryption tool gaining popularity. It’s designed for simplicity: no configuration, explicit keys, post-quantum ready.

However, age lacks signatures.

Capability	GPG	age
Encryption	Yes	Yes
Signing	Yes	No
Web of trust	Yes	No
Key servers	Yes	No

dotsecenv needs signatures for trust. Without cryptographic signatures:

• You can’t verify who created a secret
• You can’t prove the integrity of vault entries
• There’s no non-repudiation for audit trails

GPG’s signing capability lets dotsecenv verify that each vault entry was created by the identity it claims to be from.

Note

age is an excellent tool for its use case (simple file encryption). It’s not a criticism—it’s a deliberate design choice by age’s creators to omit signing for simplicity.

---

Why Not SOPS?

SOPS (Secrets OPerationS) is Mozilla’s well-designed tool for encrypting configuration files. It’s excellent for production use cases.

What SOPS Does Well

• Encrypts existing YAML/JSON files in-place
• Supports multiple backends (GPG, AWS KMS, GCP KMS, Azure Key Vault)
• Battle-tested in production environments
• Great for CI/CD secrets injection

Where dotsecenv Differs

Aspect	dotsecenv	SOPS
Primary use case	Developer workflow	Production config
Identity management	First-class	None (just keys)
Shell integration	Built-in plugins	Use with direnv
Audit trail	Append-only vault	Git history
Multi-user UX	Share/revoke commands	Manual key management

Simply put: UX

SOPS’s real power comes from cloud KMS integration—AWS KMS, GCP KMS, Azure Key Vault. These are centralized, managed services. Powerful, but:

• Require cloud accounts
• Not free
• Not fully offline

dotsecenv takes a decentralized, offline approach. Your GPG keys, your control.

Note

SOPS can use GPG alone, but the multi-identity workflow requires manual key management. dotsecenv provides share and revoke commands specifically for this.

---

Non-Goals

dotsecenv deliberately does not aim to:

Manage Production Secrets

dotsecenv is for the development lifecycle (SDLC)—bringing simple encryption to developers’ daily operations.

For production, consider:

• HashiCorp Vault (dynamic secrets, PKI, enterprise features)
• AWS Secrets Manager / GCP Secret Manager
• Kubernetes Secrets with external operators

Centralize Key Management

No key servers. No cloud dependencies. Everything works offline with local GPG keys.

Protect against Time-Tampering

dotsecenv trusts the system clock. If you set your clock to the past before storing a secret, that timestamp will be recorded.

This is intentional: an attacker with write access can’t modify existing entries anyway—each entry includes the originating fingerprint and a signature by the corresponding secret key.

Protect against History Erasure

The append-only design means:

• Old entries remain readable to original recipients
• Revocation doesn’t delete history
• Defrag can compact, but auditability will be lost (unless changes are committed to a git repository)

---

Threat Model Summary

dotsecenv protects against:

• Accidental git commits (secrets are encrypted)
• Unauthorized file access (GPG encryption)
• Tampering (cryptographic signatures)
• Plaintext on disk (always encrypted at rest)

dotsecenv does NOT protect against:

• Root/admin access (can read memory)
• Compromised GPG private key
• Post-decryption environment snooping
• Quantum attacks (current GPG algorithms)

See Security Model for details.

---

Composability in Practice

dotsecenv is designed to work alongside other tools:

# With git
git add vault && git commit -m "Add API keys"

# With shell integration
curl -fsSL https://raw.githubusercontent.com/dotsecenv/plugin/main/install.sh | bash

# With scripts
DB_PASS=$(dotsecenv secret get DATABASE_PASSWORD)
psql "postgresql://user:$DB_PASS@host/db"

# With CI/CD
echo "$GPG_PRIVATE_KEY" | gpg --import
export API_KEY=$(dotsecenv secret get API_KEY)
./deploy.sh

The vault is just a file. Secrets come through stdout. JSON output for parsing. Standard UNIX patterns.