From 871bfd7dfd31a4c521c4f6687b151f9759a856ff Mon Sep 17 00:00:00 2001 From: jubnl Date: Wed, 1 Apr 2026 09:47:31 +0200 Subject: [PATCH] fix: make ENCRYPTION_KEY optional with backwards-compatible fallback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit process.exit(1) when ENCRYPTION_KEY is unset was a breaking change for existing installs — a plain git pull would prevent the server from starting. Replace with a three-step fallback: 1. ENCRYPTION_KEY env var (explicit, takes priority) 2. data/.jwt_secret (existing installs: encrypted data stays readable after upgrade with zero manual intervention) 3. data/.encryption_key auto-generated on first start (fresh installs) A warning is logged when falling back to the JWT secret so operators are nudged toward setting ENCRYPTION_KEY explicitly. Update README env table and Docker Compose comment to reflect that ENCRYPTION_KEY is recommended but no longer required. --- README.md | 11 ++-------- server/src/config.ts | 50 ++++++++++++++++++++++++++++++++------------ 2 files changed, 39 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index ebf7c6ce..56443774 100644 --- a/README.md +++ b/README.md @@ -117,13 +117,6 @@ TREK works as a Progressive Web App — no App Store needed:
Docker Compose (recommended for production) -First, create a `.env` file next to your `docker-compose.yml`: - -```bash -# Generate a random encryption key (required) -echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env -``` - ```yaml services: app: @@ -145,7 +138,7 @@ services: environment: - NODE_ENV=production - PORT=3000 - - ENCRYPTION_KEY=${ENCRYPTION_KEY} # Required — see .env setup above + - ENCRYPTION_KEY=${ENCRYPTION_KEY:-} # Recommended. Generate with: openssl rand -hex 32. If unset, falls back to data/.jwt_secret (existing installs) or auto-generates a key (fresh installs). - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-} # Comma-separated origins for CORS and email notification links - TZ=${TZ:-UTC} # Timezone for logs, reminders and scheduled tasks (e.g. Europe/Berlin) - LOG_LEVEL=${LOG_LEVEL:-info} # info = concise user actions; debug = verbose admin-level details @@ -267,7 +260,7 @@ trek.yourdomain.com { | **Core** | | | | `PORT` | Server port | `3000` | | `NODE_ENV` | Environment (`production` / `development`) | `production` | -| `ENCRYPTION_KEY` | **Required.** At-rest encryption key for stored secrets (API keys, MFA, SMTP, OIDC). Generate with `openssl rand -hex 32`. **Upgrading:** set to the contents of `./data/.jwt_secret` to keep existing encrypted data readable. | — | +| `ENCRYPTION_KEY` | At-rest encryption key for stored secrets (API keys, MFA, SMTP, OIDC). Recommended: generate with `openssl rand -hex 32`. If unset, falls back to `data/.jwt_secret` (existing installs) or auto-generates a key (fresh installs). | Auto | | `TZ` | Timezone for logs, reminders and cron jobs (e.g. `Europe/Berlin`) | `UTC` | | `LOG_LEVEL` | `info` = concise user actions, `debug` = verbose details | `info` | | `ALLOWED_ORIGINS` | Comma-separated origins for CORS and email links | same-origin | diff --git a/server/src/config.ts b/server/src/config.ts index a0fc620e..d67d4964 100644 --- a/server/src/config.ts +++ b/server/src/config.ts @@ -39,19 +39,43 @@ export function updateJwtSecret(newSecret: string): void { // Keeping it separate from JWT_SECRET means you can rotate session tokens without // invalidating all stored encrypted data, and vice-versa. // -// Upgrade note: if you already have encrypted data stored under a previous build -// that used JWT_SECRET for encryption, set ENCRYPTION_KEY to the value of your -// old JWT_SECRET so existing encrypted values continue to decrypt correctly. -// After re-saving all credentials via the admin panel you can switch to a new -// random ENCRYPTION_KEY. -const ENCRYPTION_KEY: string = process.env.ENCRYPTION_KEY || ''; +// Resolution order: +// 1. ENCRYPTION_KEY env var — explicit, always takes priority. +// 2. data/.jwt_secret — used automatically for existing installs that upgrade +// without setting ENCRYPTION_KEY; encrypted data stays readable with no +// manual intervention required. +// 3. data/.encryption_key — auto-generated and persisted on first start of a +// fresh install where neither of the above is available. +let _encryptionKey: string = process.env.ENCRYPTION_KEY || ''; -if (!ENCRYPTION_KEY) { - console.error('FATAL: ENCRYPTION_KEY is not set.'); - console.error('If this occurs after an update, set ENCRYPTION_KEY to the value of your old JWT secret.'); - console.error('Your JWT secret is stored in data/.jwt_secret (host path: ./data/.jwt_secret).'); - console.error('For a fresh install, generate a random key: openssl rand -hex 32'); - process.exit(1); +if (!_encryptionKey) { + // Fallback 1: existing install — reuse the JWT secret so previously encrypted + // values remain readable after an upgrade. + try { + _encryptionKey = fs.readFileSync(jwtSecretFile, 'utf8').trim(); + console.warn('WARNING: ENCRYPTION_KEY is not set. Falling back to JWT secret for at-rest encryption.'); + console.warn('Set ENCRYPTION_KEY explicitly to decouple encryption from JWT signing (recommended).'); + } catch { + // JWT secret not found — must be a fresh install, fall through. + } } -export { ENCRYPTION_KEY }; +if (!_encryptionKey) { + // Fallback 2: fresh install — auto-generate a dedicated key. + const encKeyFile = path.join(dataDir, '.encryption_key'); + try { + _encryptionKey = fs.readFileSync(encKeyFile, 'utf8').trim(); + } catch { + _encryptionKey = crypto.randomBytes(32).toString('hex'); + try { + if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true }); + fs.writeFileSync(encKeyFile, _encryptionKey, { mode: 0o600 }); + console.log('Generated and saved encryption key to', encKeyFile); + } catch (writeErr: unknown) { + console.warn('WARNING: Could not persist encryption key to disk:', writeErr instanceof Error ? writeErr.message : writeErr); + console.warn('Set ENCRYPTION_KEY env var to avoid losing access to encrypted secrets on restart.'); + } + } +} + +export const ENCRYPTION_KEY = _encryptionKey;