feat(security): encrypt userId and userHash at rest with AES-256-GCM

Store game credentials encrypted in SQLite so a database leak cannot be
directly exploited. A stolen DB file yields only opaque ciphertext.

Implementation
- src/bot/utils/crypto.ts (new): AES-256-GCM helpers using Node.js crypto.
  Key loaded from ENCRYPTION_KEY env var (64-char hex / 32 bytes).
  Ciphertext format: enc1:<iv_hex>:<authTag_hex>:<ciphertext_hex>.
  Key is validated eagerly at module load time (fail-fast).
- src/bot/database/userManager.ts: encrypt on write, decrypt on read.
  saveCredentials() rejects empty userId/userHash.
  migratePlaintextCredentials() transparently upgrades existing rows on
  startup; each field is migrated independently (handles mixed-state rows).
- src/bot/bot.ts: calls migratePlaintextCredentials() after DB init.
- src/test/setup.ts: sets ENCRYPTION_KEY to a clearly non-secret
  'deadbeef'-repeated test fixture to avoid secret-scanner false positives.
- src/bot/database/userManager.test.ts: 5 new migration tests; existing
  tests updated to assert encrypted-at-rest storage.

Configuration
- .env.example: documents ENCRYPTION_KEY with generation hint.
- docker-compose.yml / docker-compose.example.yml: forwards ENCRYPTION_KEY
  into the container.

Docs updated in README, docs/development.md, docs/full-documentation.md,
docs/podman.md, docs/github-secrets.md: ENCRYPTION_KEY listed as a required
variable with openssl rand -hex 32 generation hint and a warning that the
key must be generated once and retained — changing it after credentials have
been saved makes those rows unreadable.

Signed-off-by: Michael Cramer <michael@bigmichi1.de>

Author: BigMichi1

.env.example

@@ -6,5 +6,10 @@ DISCORD_CHANNEL_ID=123456789012345679
 # Database
 DB_PATH=./data/idle.db
 
+# Encryption key for sensitive credentials stored in the database (userId, userHash).
+# Must be a 64-character hex string (32 random bytes). Generate with:
+#   openssl rand -hex 32
+ENCRYPTION_KEY=your_64_char_hex_key_here
+
 # Environment
 NODE_ENV=development

README.md

@@ -36,7 +36,8 @@ mise run install
 
 # 2. Configure environment
 cp .env.example .env
-# Edit .env with your DISCORD_TOKEN and server IDs
+# Edit .env with your DISCORD_TOKEN, server IDs, and generate an encryption key:
+#   openssl rand -hex 32  → paste result as ENCRYPTION_KEY
 
 # 3. Start the bot
 mise run dev
@@ -60,8 +61,12 @@ Deploy the bot using the pre-built Docker image:
 # 1. Copy the example compose file
 cp docker-compose.example.yml docker-compose.yml
 
-# 2. Set your Discord token
+# 2. Set required environment variables
 export DISCORD_TOKEN=your_bot_token_here
+# Generate ENCRYPTION_KEY once and store it safely (e.g. in a .env file or secret store).
+# ⚠️  Never regenerate this value for an existing database — previously saved credentials
+#     will become unreadable if the key changes.
+export ENCRYPTION_KEY=$(openssl rand -hex 32)
 
 # 3. Start the bot
 docker-compose up -d

docker-compose.example.yml

@@ -39,6 +39,10 @@ services:
       # Find this ID by enabling Developer Mode in Discord → right-click the bot → Copy User ID.
       DISCORD_CODE_AUTHOR_ID: ${DISCORD_CODE_AUTHOR_ID:-}
 
+      # Required: 64-character hex encryption key for credentials stored in the database.
+      # Generate with: openssl rand -hex 32
+      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
+      
       # Database location (inside container)
       DB_PATH: /app/data/idle.db
 

docker-compose.yml

@@ -11,6 +11,7 @@ services:
       DISCORD_TOKEN: ${DISCORD_TOKEN}
       DISCORD_GUILD_ID: ${DISCORD_GUILD_ID:-}
       DISCORD_CHANNEL_ID: ${DISCORD_CHANNEL_ID:-357247482247380994}
+      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
       DB_PATH: /app/data/idle.db
       NODE_ENV: production
     volumes:

docs/development.md

@@ -302,6 +302,10 @@ DISCORD_TOKEN      # Bot token from Discord Developer Portal
 DISCORD_GUILD_ID   # Server ID (for guild-specific commands)
 DISCORD_CHANNEL_ID # Channel ID (for auto code scanning)
 DISCORD_CODE_AUTHOR_ID # User/bot ID that posts promo codes (filters backfill to that author only)
+ENCRYPTION_KEY     # Required — 64-char hex key (32 bytes) for AES-256-GCM credential encryption
+                   # Generate: openssl rand -hex 32
+                   # Note: users.user_id and users.user_hash are stored as AES-256-GCM
+                   # ciphertext (enc1:<iv>:<authTag>:<ct>), not as raw int/token values.
 DB_PATH            # Database file path (default: ./data/idle.db)
 NODE_ENV           # development or production
 ```

docs/full-documentation.md

@@ -39,6 +39,9 @@ cp .env.example .env
 # - DISCORD_GUILD_ID (your server ID)
 # - DISCORD_CHANNEL_ID (where bot scans for codes)
 # - DISCORD_CODE_AUTHOR_ID (ID of the bot that posts codes, e.g. Idle Champions #combinations)
+# - ENCRYPTION_KEY — generate once with: openssl rand -hex 32
+#   ⚠️  Store this value safely and never regenerate it for an existing database;
+#       changing the key makes previously saved credentials unreadable.
 
 # 4. Start the bot
 mise run dev
@@ -242,6 +245,9 @@ DISCORD_TOKEN=your_bot_token_here
 DISCORD_GUILD_ID=1214259114725605436
 DISCORD_CHANNEL_ID=1502624358055809104
 DISCORD_CODE_AUTHOR_ID=1502625533236744222
+# Required: 64-char hex key for AES-256-GCM credential encryption
+# Generate with: openssl rand -hex 32
+ENCRYPTION_KEY=your_64_char_hex_key_here
 DB_PATH=./data/idle.db
 NODE_ENV=development
 ```

docs/github-secrets.md

@@ -46,6 +46,8 @@ DISCORD_TOKEN=your_discord_bot_token_here
 DISCORD_GUILD_ID=your_guild_id_here
 DISCORD_CHANNEL_ID=your_channel_id_here
 DISCORD_CODE_AUTHOR_ID=your_code_author_bot_id_here
+# Required: generate with: openssl rand -hex 32
+ENCRYPTION_KEY=your_64_char_hex_key_here
 DB_PATH=/app/data/idle.db
 NODE_ENV=development
 ```

docs/podman.md

@@ -52,6 +52,10 @@ sudo pip3 install podman-compose
 # Copy and configure
 cp docker-compose.example.yml docker-compose.yml
 export DISCORD_TOKEN=your_bot_token_here
+# Generate ENCRYPTION_KEY once, then persist the value (e.g. in a .env file).
+# ⚠️  Never regenerate this for an existing database — previously saved credentials
+#     will become unreadable if the key changes.
+export ENCRYPTION_KEY=$(openssl rand -hex 32)
 
 # Start the bot
 podman-compose up -d
@@ -103,6 +107,10 @@ export DISCORD_TOKEN=your_bot_token_here
 export DISCORD_GUILD_ID=optional_guild_id
 export DISCORD_CHANNEL_ID=optional_channel_id
 export DISCORD_CODE_AUTHOR_ID=optional_code_author_bot_id
+# Generate ENCRYPTION_KEY once and persist it (e.g. in a .env file or secret store).
+# ⚠️  Never regenerate this for an existing database — previously saved credentials
+#     will become unreadable if the key changes.
+export ENCRYPTION_KEY=$(openssl rand -hex 32)
 ```
 
 Or add them to your `docker-compose.yml` (or `.env` file if using podman-compose).

src/bot/bot.ts

@@ -5,6 +5,7 @@ import { backfillChannelHistory } from './handlers/backfillHandler';
 import { enqueueAutoRedeem, setDiscordClient } from './handlers/autoRedeemer';
 import { codeManager } from './database/codeManager';
 import { backfillManager } from './database/backfillManager';
+import { userManager } from './database/userManager';
 import { initDebugLogger } from './utils/debugLogger';
 import logger from './utils/logger';
 import { apiRequestLogger } from './utils/apiRequestLogger';
@@ -78,6 +79,7 @@ client.on(Events.ClientReady, async () => {
 
   try {
     initializeDatabase();
+    await userManager.migratePlaintextCredentials();
 
     // Check if startup backfill should run
     const shouldBackfill = await backfillManager.shouldRunStartupBackfill();

src/bot/database/userManager.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, beforeAll, beforeEach } from 'bun:test';
 import { db, initializeDatabase } from './db';
 import { userManager } from './userManager';
 import { users, redeemedCodes, pendingCodes } from './schema/index';
+import { isEncrypted, encrypt } from '../utils/crypto';
 
 beforeAll(() => {
   initializeDatabase();
@@ -25,17 +26,24 @@ describe('saveCredentials', () => {
     const rows = db.select().from(users).all();
     expect(rows).toHaveLength(1);
     expect(rows[0].discordId).toBe('user-1');
-    expect(rows[0].userId).toBe('111');
-    expect(rows[0].userHash).toBe('hash-a');
+    // Credentials are encrypted at rest — raw DB values must not be plaintext
+    expect(rows[0].userId).not.toBe('111');
+    expect(rows[0].userHash).not.toBe('hash-a');
+    // Decrypted values match originals
+    const creds = await userManager.getCredentials('user-1');
+    expect(creds?.userId).toBe('111');
+    expect(creds?.userHash).toBe('hash-a');
   });
 
   test('upserts existing user credentials', async () => {
     await userManager.saveCredentials({ discordId: 'user-1', userId: '111', userHash: 'hash-a' });
     await userManager.saveCredentials({ discordId: 'user-1', userId: '222', userHash: 'hash-b' });
     const rows = db.select().from(users).all();
     expect(rows).toHaveLength(1);
-    expect(rows[0].userId).toBe('222');
-    expect(rows[0].userHash).toBe('hash-b');
+    // Decrypted values reflect the latest upsert
+    const creds = await userManager.getCredentials('user-1');
+    expect(creds?.userId).toBe('222');
+    expect(creds?.userHash).toBe('hash-b');
   });
 
   test('stores optional server field', async () => {
@@ -215,3 +223,80 @@ describe('getAllUsersWithAutoRedeem', () => {
     expect(await userManager.getAllUsersWithAutoRedeem()).toEqual([]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// migratePlaintextCredentials
+// ---------------------------------------------------------------------------
+describe('migratePlaintextCredentials', () => {
+  test('is a no-op when the table is empty', async () => {
+    await userManager.migratePlaintextCredentials();
+    expect(db.select().from(users).all()).toHaveLength(0);
+  });
+
+  test('encrypts plaintext userId and userHash, preserving decrypted values', async () => {
+    // Seed a row with plaintext credentials directly (bypassing saveCredentials)
+    db.insert(users).values({ discordId: 'user-1', userId: '111', userHash: 'hash-a' }).run();
+
+    await userManager.migratePlaintextCredentials();
+
+    const row = db.select().from(users).get();
+    // Both fields must now be in encrypted format
+    expect(isEncrypted(row!.userId)).toBe(true);
+    expect(isEncrypted(row!.userHash)).toBe(true);
+    // Decrypted values must match the original plaintext
+    const creds = await userManager.getCredentials('user-1');
+    expect(creds?.userId).toBe('111');
+    expect(creds?.userHash).toBe('hash-a');
+  });
+
+  test('migrates multiple plaintext rows independently', async () => {
+    db.insert(users).values([
+      { discordId: 'user-1', userId: '111', userHash: 'hash-a' },
+      { discordId: 'user-2', userId: '222', userHash: 'hash-b' },
+    ]).run();
+
+    await userManager.migratePlaintextCredentials();
+
+    const creds1 = await userManager.getCredentials('user-1');
+    const creds2 = await userManager.getCredentials('user-2');
+    expect(creds1?.userId).toBe('111');
+    expect(creds1?.userHash).toBe('hash-a');
+    expect(creds2?.userId).toBe('222');
+    expect(creds2?.userHash).toBe('hash-b');
+  });
+
+  test('leaves already-encrypted rows unchanged (no double-encryption)', async () => {
+    // Seed via saveCredentials so the row is already encrypted
+    await userManager.saveCredentials({ discordId: 'user-1', userId: '111', userHash: 'hash-a' });
+    const before = db.select().from(users).get();
+
+    await userManager.migratePlaintextCredentials();
+
+    const after = db.select().from(users).get();
+    // Raw stored values must be identical — no re-encryption occurred
+    expect(after!.userId).toBe(before!.userId);
+    expect(after!.userHash).toBe(before!.userHash);
+    // Decrypted values still correct
+    const creds = await userManager.getCredentials('user-1');
+    expect(creds?.userId).toBe('111');
+    expect(creds?.userHash).toBe('hash-a');
+  });
+
+  test('encrypts only the plaintext field in a mixed-state row', async () => {
+    // Seed a row where userId is already encrypted but userHash is still plaintext
+    const encryptedUserId = encrypt('111');
+    db.insert(users).values({ discordId: 'user-1', userId: encryptedUserId, userHash: 'hash-a' }).run();
+
+    await userManager.migratePlaintextCredentials();
+
+    const row = db.select().from(users).get();
+    // userId must be the same encrypted value (not double-encrypted)
+    expect(row!.userId).toBe(encryptedUserId);
+    // userHash must now be encrypted
+    expect(isEncrypted(row!.userHash)).toBe(true);
+    // Both decrypt correctly
+    const creds = await userManager.getCredentials('user-1');
+    expect(creds?.userId).toBe('111');
+    expect(creds?.userHash).toBe('hash-a');
+  });
+});