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/token_secret
41```
42
43**Usage in config:**
44```toml
45[auth]
46token_secret = "gordon/auth/token_secret"  # Path in pass store
47```
48
49**Benefits:**
50- GPG-encrypted storage
51- Version control friendly (encrypted files)
52- Standard Unix tooling
53- Works with team GPG keys
54
55**Route secrets storage:**
56- `gordon secrets set` stores per-domain secrets in pass under `gordon/env/<sanitized-domain>/<KEY>` (dots/colons/slashes → underscores)
57- Existing `.env` files are auto-migrated on startup and renamed to `.env.migrated`
58- Attachment secrets are stored under `gordon/env/attachments/<container-name>/<KEY>` with a `.keys` manifest
59- Use `gordon secrets set <domain> --attachment <service> KEY=value` to manage them
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**Attachment secrets storage:**
102- Attachment secrets are stored in `gordon-<container-name>.env` files alongside domain env files
103- Use `${sops:...}` syntax inside attachment env files to resolve encrypted values
104- Use `gordon secrets set <domain> --attachment <service> KEY=value` to manage them
105
106### Unsafe (Development Only)
107
108Stores secrets as plain text files:
109
110```toml
111[auth]
112secrets_backend = "unsafe"
113```
114
115**Storage location:**
116```
117{data_dir}/secrets/
118├── gordon/
119│   └── auth/
120│       └── token_secret
121```
122
123**Attachment secrets:**
124- Stored as `gordon-<container-name>.env` files in the env directory
125- Example: `gordon-app__mydomain__com-postgres.env`
126- Use `gordon secrets set <domain> --attachment <service> KEY=value` to manage them
127
128**Usage:**
129```bash
130# Create secret
131mkdir -p ~/.gordon/secrets/gordon/auth
132echo "your-token-secret" > ~/.gordon/secrets/gordon/auth/token_secret
133```
134
135> **Warning:** Only use for local development. Secrets are stored in plain text.
136
137## Secret Provider Syntax
138
139In environment files, reference secrets using provider syntax:
140
141### Pass Provider
142
143```bash
144# ${pass:<path>}
145DATABASE_PASSWORD=${pass:myapp/database/password}
146API_KEY=${pass:myapp/api-key}
147```
148
149### SOPS Provider
150
151```bash
152# ${sops:<file>:<key.path>}
153DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
154API_SECRET=${sops:production.yaml:api.secret.key}
155```
156
157## Examples
158
159### Production with Pass
160
161```toml
162[auth]
163enabled = true
164secrets_backend = "pass"
165token_secret = "gordon/auth/token_secret"
166```
167
168```bash
169# Setup
170pass insert gordon/auth/token_secret
171# Enter a random 32+ character string
172
173# Generate tokens
174gordon auth token generate --subject deploy --expiry 0
175```
176
177### Development with Unsafe
178
179```toml
180[auth]
181enabled = false
182secrets_backend = "unsafe"
183```
184
185### Enterprise with SOPS
186
187```toml
188[auth]
189enabled = true
190secrets_backend = "sops"
191token_secret = "gordon/auth/token_secret"
192```
193
194Environment file:
195```bash
196# ~/.gordon/env/app_company_com.env
197NODE_ENV=production
198DATABASE_URL=postgresql://db:5432/app
199DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
200API_KEY=${sops:secrets.yaml:api.key}
201JWT_SECRET=${sops:secrets.yaml:jwt.secret}
202```
203
204## Security Recommendations
205
2061. **Production**: Always use `pass` or `sops` backend
2072. **Never commit**: Don't commit unencrypted secrets to git
2083. **Rotate regularly**: Regenerate tokens and passwords periodically
2094. **Least privilege**: Use separate secrets per environment
2105. **Path validation**: SOPS provider rejects absolute paths and path traversal attempts for security
211
212## Related
213
214- [Authentication](./auth.md)
215- [Environment Variables](./env.md)
216- [Configuration Overview](./index.md)