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 one 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 handles encryption and key management, git handles version control and distribution, and your shell handles environment variable loading. dotsecenv adds a minimal layer of usability and relies on those 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.

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

The short answer is UX.

SOPS’s real power comes from cloud KMS integration (AWS KMS, GCP KMS, Azure Key Vault). These are centralized, managed services. Powerful, but they require cloud accounts, they’re not free, and they’re not fully offline.

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

Non-Goals

dotsecenv deliberately does not aim to:

Manage Production Secrets

dotsecenv is for the development lifecycle (SDLC). It brings 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, since 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.