Security architecture
env-sync uses defense-in-depth across three explicit security modes. No implicit trust — you choose the model that fits your threat profile.
Security baseline by mode
| Dimension | dev-plaintext-http | trusted-owner-ssh | secure-peer |
|---|---|---|---|
| Encryption at rest | None | Plaintext default (optional AGE) | AGE encrypted (mandatory) |
| Encryption in transit | None | SSH encryption | HTTPS + mTLS (TLS 1.3) |
| Peer authentication | None | SSH keys | Mutual TLS certificates + approval |
| Risk level | Debug only — not for real secrets | Strong when all hosts are equally trusted | Strong for cross-owner boundaries |
Secure-peer trust model
- No global root CA — trust is deployment-local with pinned certificates, not dependent on external certificate authorities.
- Peer registry — tracks pending, approved, and revoked states for every peer.
- Signed membership events — approve/revoke actions are cryptographically signed and replicated across all peers.
- Replay protection — monotonic event IDs and timestamp validation prevent event replay attacks.
- Offline catch-up — peers that were offline during membership changes receive signed events on next sync.
Threat model
trusted-owner-ssh
- Strength: Mature SSH transport security, operational simplicity, and wide ecosystem support.
- Trade-off: Broad trust — compromise of one peer can impact others. All peers have equivalent access.
- Mitigation: Enable optional AGE encryption for defense-in-depth. Rotate SSH keys regularly.
secure-peer
- Strength: Explicit authorization required. Mandatory encryption at rest. No shell access shared between peers.
- Strength: mTLS reduces blast radius compared to SSH trust mesh — peers authenticate without system-level access.
- Trade-off: Higher operational overhead — invitation/approval workflow and identity material management required.
- Mitigation: Regular peer audits. Revoke compromised peers immediately — revocation propagates via signed events.
Cryptographic primitives
| Component | Algorithm | Purpose |
|---|---|---|
| AGE encryption | X25519 + ChaCha20-Poly1305 | At-rest encryption of secret values |
| mTLS certificates | TLS 1.3 (X.509) | In-transit encryption and peer authentication |
| Membership events | Signed with transport key | Cryptographic proof of peer approval/revocation |
| SSH transport | Ed25519 / RSA keys | Encrypted file transfer in trusted-owner mode |
Operational security checklist
- Keep file permissions strict —
600for secrets files. - Never log secret values — env-sync's logging respects this boundary.
- Audit approved peers regularly in secure-peer mode.
- Use backups and key lifecycle controls during membership changes.
- Enable AGE encryption in trusted-owner mode for defense-in-depth.
- Revoke and rotate keys for any compromised peer immediately.