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### SOPS
58
59Uses Mozilla SOPS for encrypted file-based secrets:
60
61```toml
62[auth]
63secrets_backend = "sops"
64```
65
66**Setup:**
67```bash
68# Install sops
69brew install sops  # macOS
70# or download from https://github.com/getsops/sops/releases
71
72# Create encrypted secrets file
73sops secrets.yaml
74```
75
76**Usage in env files:**
77```bash
78# ~/.gordon/env/app_mydomain_com.env
79API_SECRET=${sops:secrets.yaml:api.secret}
80DB_PASSWORD=${sops:secrets.yaml:database.password}
81```
82
83**Benefits:**
84- Multiple encryption backends (AWS KMS, GCP KMS, Azure Key Vault, PGP)
85- YAML/JSON file encryption
86- Git-friendly (encrypted files in repo)
87
88### Unsafe (Development Only)
89
90Stores secrets as plain text files:
91
92```toml
93[auth]
94secrets_backend = "unsafe"
95```
96
97**Storage location:**
98```
99{data_dir}/secrets/
100├── gordon/
101│   └── auth/
102│       ├── password_hash
103│       └── token_secret
104```
105
106**Usage:**
107```bash
108# Create secret
109mkdir -p ~/.gordon/secrets/gordon/auth
110echo "your-bcrypt-hash" > ~/.gordon/secrets/gordon/auth/password_hash
111```
112
113> **Warning:** Only use for local development. Secrets are stored in plain text.
114
115## Secret Provider Syntax
116
117In environment files, reference secrets using provider syntax:
118
119### Pass Provider
120
121```bash
122# ${pass:<path>}
123DATABASE_PASSWORD=${pass:myapp/database/password}
124API_KEY=${pass:myapp/api-key}
125```
126
127### SOPS Provider
128
129```bash
130# ${sops:<file>:<key.path>}
131DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
132API_SECRET=${sops:production.yaml:api.secret.key}
133```
134
135## Examples
136
137### Production with Pass
138
139```toml
140[auth]
141enabled = true
142secrets_backend = "pass"
143token_secret = "gordon/auth/token_secret"
144```
145
146```bash
147# Setup
148pass insert gordon/auth/token_secret
149# Enter a random 32+ character string
150
151# Generate tokens
152gordon auth token generate --subject deploy --expiry 0
153```
154
155### Development with Unsafe
156
157```toml
158[auth]
159enabled = false
160secrets_backend = "unsafe"
161```
162
163### Enterprise with SOPS
164
165```toml
166[auth]
167enabled = true
168secrets_backend = "sops"
169token_secret = "gordon/auth/token_secret"
170```
171
172Environment file:
173```bash
174# ~/.gordon/env/app_company_com.env
175NODE_ENV=production
176DATABASE_URL=postgresql://db:5432/app
177DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
178API_KEY=${sops:secrets.yaml:api.key}
179JWT_SECRET=${sops:secrets.yaml:jwt.secret}
180```
181
182## Security Recommendations
183
1841. **Production**: Always use `pass` or `sops` backend
1852. **Never commit**: Don't commit unencrypted secrets to git
1863. **Rotate regularly**: Regenerate tokens and passwords periodically
1874. **Least privilege**: Use separate secrets per environment
188
189## Related
190
191- [Authentication](./auth.md)
192- [Environment Variables](./env.md)
193- [Configuration Overview](./index.md)