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**Route secrets storage:**
93- Domain secrets stay in `.env` files
94- Use `${sops:...}` syntax to resolve encrypted values
95
96### Unsafe (Development Only)
97
98Stores secrets as plain text files:
99
100```toml
101[auth]
102secrets_backend = "unsafe"
103```
104
105**Storage location:**
106```
107{data_dir}/secrets/
108├── gordon/
109│   └── auth/
110│       ├── password_hash
111│       └── token_secret
112```
113
114**Usage:**
115```bash
116# Create secret
117mkdir -p ~/.gordon/secrets/gordon/auth
118echo "your-bcrypt-hash" > ~/.gordon/secrets/gordon/auth/password_hash
119```
120
121> **Warning:** Only use for local development. Secrets are stored in plain text.
122
123## Secret Provider Syntax
124
125In environment files, reference secrets using provider syntax:
126
127### Pass Provider
128
129```bash
130# ${pass:<path>}
131DATABASE_PASSWORD=${pass:myapp/database/password}
132API_KEY=${pass:myapp/api-key}
133```
134
135### SOPS Provider
136
137```bash
138# ${sops:<file>:<key.path>}
139DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
140API_SECRET=${sops:production.yaml:api.secret.key}
141```
142
143## Examples
144
145### Production with Pass
146
147```toml
148[auth]
149enabled = true
150secrets_backend = "pass"
151token_secret = "gordon/auth/token_secret"
152```
153
154```bash
155# Setup
156pass insert gordon/auth/token_secret
157# Enter a random 32+ character string
158
159# Generate tokens
160gordon auth token generate --subject deploy --expiry 0
161```
162
163### Development with Unsafe
164
165```toml
166[auth]
167enabled = false
168secrets_backend = "unsafe"
169```
170
171### Enterprise with SOPS
172
173```toml
174[auth]
175enabled = true
176secrets_backend = "sops"
177token_secret = "gordon/auth/token_secret"
178```
179
180Environment file:
181```bash
182# ~/.gordon/env/app_company_com.env
183NODE_ENV=production
184DATABASE_URL=postgresql://db:5432/app
185DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
186API_KEY=${sops:secrets.yaml:api.key}
187JWT_SECRET=${sops:secrets.yaml:jwt.secret}
188```
189
190## Security Recommendations
191
1921. **Production**: Always use `pass` or `sops` backend
1932. **Never commit**: Don't commit unencrypted secrets to git
1943. **Rotate regularly**: Regenerate tokens and passwords periodically
1954. **Least privilege**: Use separate secrets per environment
196
197## Related
198
199- [Authentication](./auth.md)
200- [Environment Variables](./env.md)
201- [Configuration Overview](./index.md)