ADRs
0007, Encryption key blocklist
Why the SDK refuses to start with known-weak ENCRYPTION_KEY values
Status: Accepted Date: 2026-03 Stakeholders: Bobby Nannier
Context
The SDK encrypts settings at rest with ENCRYPTION_KEY as the master key (see ADR 0006). If an operator sets a weak key, empty string, "changeme", a value copy-pasted from a tutorial, the encryption protects nothing.
Common operator mistakes:
- Leaving
.env.example's placeholder unchanged. - Using
"00000000000000000000000000000000""for testing" and forgetting to rotate. - Copy-pasting a public sample value.
These mistakes are silent, the system runs fine; secrets are "encrypted." But the encryption is decorative.
Decision
The SDK ships a blocklist of known-weak / known-public ENCRYPTION_KEY values. On startup, the SDK refuses to start if ENCRYPTION_KEY is on the list.
The blocklist lives in sdk/src/blocklist.ts. Adding to it is fast and non-breaking.
What's on the list
- Empty string.
"changeme","replaceme","replace_me","todo".- All-zero (
"00000000000000000000000000000000"and base64 equivalents). - Sample values from
.env.examplefiles in this repo's history. - Sample values from popular tutorials.
Consequences
- An operator who tries to "just set a value to try things" gets a loud error instead of a silently-broken deployment.
- The cost: tiny startup check, no measurable performance impact.
- The blocklist grows as we discover more common-mistake values. Not breaking, any non-blocked value continues to work.