1# Secrets Configuration
2
3Configure how Gordon stores and retrieves sensitive data.
4
5## Configuration
6
7The secrets backend is configured within the `[auth]` section:
8
9```toml
10[auth]
11secrets_backend = "pass"  # "pass", "sops", or "unsafe"
12```
13
14## Options
15
16| Option | Type | Default | Description |
17|--------|------|---------|-------------|
18| `secrets_backend` | string | `"unsafe"` | Secrets storage backend |
19
20## Backends
21
22### Pass (Recommended for Production)
23
24Uses the Unix password manager (`pass`) for secure secret storage:
25
26```toml
27[auth]
28secrets_backend = "pass"
29```
30
31**Setup:**
32```bash
33# Install pass
34sudo apt install pass
35
36# Initialize with GPG key
37pass init your-gpg-key-id
38
39# Store secrets
40pass insert gordon/auth/password_hash
41pass insert gordon/auth/token_secret
42```
43
44**Usage in config:**
45```toml
46[auth]
47password_hash = "gordon/auth/password_hash"  # Path in pass store
48token_secret = "gordon/auth/token_secret"
49```
50
51**Benefits:**
52- GPG-encrypted storage
53- Version control friendly (encrypted files)
54- Standard Unix tooling
55- Works with team GPG keys
56
57**Route secrets storage:**
58- `gordon secrets set` stores per-domain secrets in pass under `gordon/env/<sanitized-domain>/<KEY>` (dots/colons/slashes → underscores)
59- Existing `.env` files are auto-migrated on startup and renamed to `.env.migrated`
60
61### SOPS
62
63Uses Mozilla SOPS for encrypted file-based secrets:
64
65```toml
66[auth]
67secrets_backend = "sops"
68```
69
70**Setup:**
71```bash
72# Install sops
73brew install sops  # macOS
74# or download from https://github.com/getsops/sops/releases
75
76# Create encrypted secrets file
77sops secrets.yaml
78```
79
80**Usage in env files:**
81```bash
82# ~/.gordon/env/app_mydomain_com.env
83API_SECRET=${sops:secrets.yaml:api.secret}
84DB_PASSWORD=${sops:secrets.yaml:database.password}
85```
86
87**Benefits:**
88- Multiple encryption backends (AWS KMS, GCP KMS, Azure Key Vault, PGP)
89- YAML/JSON file encryption
90- Git-friendly (encrypted files in repo)
91
92**Security:**
93- Absolute paths are rejected to prevent arbitrary file access
94- Path traversal (`..`) is blocked
95- Only relative paths from your config directory are allowed
96
97**Route secrets storage:**
98- Domain secrets stay in `.env` files
99- Use `${sops:...}` syntax to resolve encrypted values
100
101### Unsafe (Development Only)
102
103Stores secrets as plain text files:
104
105```toml
106[auth]
107secrets_backend = "unsafe"
108```
109
110**Storage location:**
111```
112{data_dir}/secrets/
113├── gordon/
114│   └── auth/
115│       ├── password_hash
116│       └── token_secret
117```
118
119**Usage:**
120```bash
121# Create secret
122mkdir -p ~/.gordon/secrets/gordon/auth
123echo "your-bcrypt-hash" > ~/.gordon/secrets/gordon/auth/password_hash
124```
125
126> **Warning:** Only use for local development. Secrets are stored in plain text.
127
128## Secret Provider Syntax
129
130In environment files, reference secrets using provider syntax:
131
132### Pass Provider
133
134```bash
135# ${pass:<path>}
136DATABASE_PASSWORD=${pass:myapp/database/password}
137API_KEY=${pass:myapp/api-key}
138```
139
140### SOPS Provider
141
142```bash
143# ${sops:<file>:<key.path>}
144DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
145API_SECRET=${sops:production.yaml:api.secret.key}
146```
147
148## Examples
149
150### Production with Pass
151
152```toml
153[auth]
154enabled = true
155secrets_backend = "pass"
156token_secret = "gordon/auth/token_secret"
157```
158
159```bash
160# Setup
161pass insert gordon/auth/token_secret
162# Enter a random 32+ character string
163
164# Generate tokens
165gordon auth token generate --subject deploy --expiry 0
166```
167
168### Development with Unsafe
169
170```toml
171[auth]
172enabled = false
173secrets_backend = "unsafe"
174```
175
176### Enterprise with SOPS
177
178```toml
179[auth]
180enabled = true
181secrets_backend = "sops"
182token_secret = "gordon/auth/token_secret"
183```
184
185Environment file:
186```bash
187# ~/.gordon/env/app_company_com.env
188NODE_ENV=production
189DATABASE_URL=postgresql://db:5432/app
190DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
191API_KEY=${sops:secrets.yaml:api.key}
192JWT_SECRET=${sops:secrets.yaml:jwt.secret}
193```
194
195## Security Recommendations
196
1971. **Production**: Always use `pass` or `sops` backend
1982. **Never commit**: Don't commit unencrypted secrets to git
1993. **Rotate regularly**: Regenerate tokens and passwords periodically
2004. **Least privilege**: Use separate secrets per environment
2015. **Path validation**: SOPS provider rejects absolute paths and path traversal attempts for security
202
203## Related
204
205- [Authentication](./auth.md)
206- [Environment Variables](./env.md)
207- [Configuration Overview](./index.md)