Refactor authentication and IMAP configuration: switch to base64-encoded storage for master password hash and IMAP config

Signed-off-by: Shahm Najeeb <Shahm_Najeeb@outlook.com>

Author: DefinetlyNotAI

README.md

@@ -65,16 +65,16 @@ MASTER_PASSWORD_BCRYPT_HASH=your-bcrypt-hash-here
 # Generate with: openssl rand -base64 32
 SESSION_SECRET=your-random-secret-here
 
-# IMAP Configuration (JSON format)
-# Add all your email accounts in this JSON structure
-IMAP_CONFIG={"accounts":[{"id":"account1","label":"Account 1","imap":{"host":"imap.example.com","port":993,"secure":true,"user":"user@example.com","password":"your-password"}}]}
+# IMAP Configuration (base64-encoded JSON)
+# Create your JSON config, then encode: Buffer.from(JSON.stringify(config)).toString('base64')
+IMAP_CONFIG=base64-encoded-json-here
 ```
 
 ### 2. IMAP Configuration Details
 
-> VERY IMPORTANT: Please escape all $ signs in passwords with a backslash (`\$`) when setting environment variables
+The `IMAP_CONFIG` environment variable accepts a base64-encoded JSON string with the following structure:
 
-The `IMAP_CONFIG` environment variable accepts a JSON object with the following structure:
+**First, create your JSON configuration:**
 
 ```json
 {
@@ -94,6 +94,16 @@ The `IMAP_CONFIG` environment variable accepts a JSON object with the following
 }
 ```
 
+**Then encode it to base64:**
+
+```javascript
+const config = {
+  "accounts": [...]
+};
+const base64Config = Buffer.from(JSON.stringify(config)).toString('base64');
+console.log(base64Config);
+```
+
 **Example with multiple accounts:**
 
 ```json
@@ -150,8 +160,8 @@ The `IMAP_CONFIG` environment variable accepts a JSON object with the following
     - User: Your full email address
     - Password: Your email password or app-specific password
 
-**Important**: The IMAP_CONFIG value must be a single-line JSON string with no line breaks when set as an environment
-variable.
+**Note**: With base64 encoding, special characters in passwords (like `$`, `#`, `!`) are automatically handled - no
+escaping needed!
 
 See [SECURITY.md](./SECURITY.md) for detailed configuration instructions.
 

SECURITY.md

@@ -57,23 +57,32 @@ It provides **read-only** access to IMAP mailboxes through a secure web interfac
 ### Required Variables
 
 ```bash
-# Master password hash (generate with bcryptjs)
+# Master password hash (base64-encoded bcrypt hash)
 MASTER_PASSWORD_BCRYPT_HASH=
 
 # Session secret (generate a random string)
 SESSION_SECRET=
 
-# IMAP configuration (JSON format)
+# IMAP configuration (base64-encoded JSON)
 IMAP_CONFIG=
 ```
 
 ### Generating MASTER_PASSWORD_HASH
 
+The master password hash is stored as a base64-encoded bcrypt hash:
+
 ```javascript
 import bcrypt from 'bcryptjs'
 
 const hash = await bcrypt.hash('your-secure-password', 10)
-console.log(hash)
+const base64Hash = Buffer.from(hash).toString('base64')
+console.log(base64Hash)
+```
+
+Or use the provided setup script:
+
+```bash
+node scripts/setup-password.js
 ```
 
 ### Generating SESSION_SECRET
@@ -84,6 +93,8 @@ openssl rand -base64 32
 
 ### IMAP Configuration Format
 
+The IMAP configuration is stored as base64-encoded JSON. First, create your JSON configuration:
+
 ```json
 {
   "accounts": [
@@ -102,6 +113,18 @@ openssl rand -base64 32
 }
 ```
 
+Then encode it to base64:
+
+```javascript
+const config = {
+  "accounts": [...]
+};
+const base64Config = Buffer.from(JSON.stringify(config)).toString('base64');
+console.log(base64Config);
+```
+
+Set the base64 string in your `.env` file as `IMAP_CONFIG`.
+
 ## Security Considerations
 
 ### Open Source

lib/auth.ts

@@ -15,9 +15,14 @@ import {cookies} from "next/headers"
 import {SessionData} from "@/types/server";
 import {SecuritySettings} from "@/lib/settings";
 
-// Master password hash stored in environment variable
-// Generate with: bcrypt.hash('your-password', 10)
-const MASTER_PASSWORD_BCRYPT_HASH = process.env.MASTER_PASSWORD_BCRYPT_HASH
+// Master password hash stored in environment variable as base64-encoded bcrypt hash
+// Generate with: Buffer.from(await bcrypt.hash('your-password', 10)).toString('base64')
+const MASTER_PASSWORD_BCRYPT_HASH_BASE64 = process.env.MASTER_PASSWORD_BCRYPT_HASH
+
+// Decode the base64-encoded bcrypt hash at runtime
+const MASTER_PASSWORD_BCRYPT_HASH = MASTER_PASSWORD_BCRYPT_HASH_BASE64
+    ? Buffer.from(MASTER_PASSWORD_BCRYPT_HASH_BASE64, 'base64').toString('utf8')
+    : undefined
 
 // Validate environment variables at runtime, not at module load
 function validateEnvironment() {

lib/imap-config.ts

@@ -24,9 +24,9 @@ export function getImapConfig(): ImapConfig {
 
     console.log("[IMAP CONFIG] Reading config from IMAP_CONFIG environment variable")
 
-    const configString = process.env.IMAP_CONFIG
+    const configBase64 = process.env.IMAP_CONFIG
 
-    if (!configString) {
+    if (!configBase64) {
         const error = new Error("IMAP_CONFIG environment variable is not set")
         console.error("[IMAP CONFIG] Failed to parse IMAP_CONFIG environment variable", {
             error: error.message,
@@ -38,7 +38,10 @@ export function getImapConfig(): ImapConfig {
 
     let config: ImapConfig
     try {
-        console.log("[IMAP CONFIG] Config environment variable read successfully")
+        console.log("[IMAP CONFIG] Decoding base64-encoded config...")
+        // Decode base64 to get JSON string
+        const configString = Buffer.from(configBase64, 'base64').toString('utf8')
+        console.log("[IMAP CONFIG] Config decoded successfully, parsing JSON...")
         config = JSON.parse(configString) as ImapConfig
     } catch (parseError) {
         console.error("[IMAP CONFIG] Failed to parse IMAP_CONFIG environment variable", {

scripts/README.md

@@ -50,10 +50,13 @@ Enter password: ********
 Step 2: Generating bcrypt hash...
 ✓ Hash generated successfully!
 
-Step 3: Updating .env file...
+Step 3: Encoding hash to base64...
+✓ Hash encoded successfully!
+
+Step 4: Updating .env file...
 ✓ .env file updated successfully!
 
-Step 4: Testing password verification...
+Step 5: Testing password verification...
   ✓ Password verification successful!
   ✓ .env file contains correct hash!
   ✓ Password matches hash from .env!

scripts/setup-password.js

@@ -6,8 +6,9 @@
  * This script will:
  * 1. Ask you for your desired master password
  * 2. Generate a bcrypt hash
- * 3. Update the .env file automatically
- * 4. Test that everything works correctly
+ * 3. Base64 encode the hash for storage
+ * 4. Update the .env file automatically
+ * 5. Test that everything works correctly
  */
 
 import bcrypt from 'bcryptjs';
@@ -94,10 +95,16 @@ async function main() {
         const hash = await bcrypt.hash(password, 10);
 
         log('✓ Hash generated successfully!', 'green');
-        log(`\nGenerated hash: ${colors.cyan}${hash}${colors.reset}\n`);
+        log(`\nGenerated bcrypt hash: ${colors.cyan}${hash}${colors.reset}`);
 
-        // Step 4: Update .env file
-        log('Step 4: Updating .env file...', 'bright');
+        // Step 4: Base64 encode the hash
+        log('\nStep 4: Encoding hash to base64...', 'bright');
+        const base64Hash = Buffer.from(hash).toString('base64');
+        log('✓ Hash encoded successfully!', 'green');
+        log(`\nBase64-encoded hash: ${colors.cyan}${base64Hash}${colors.reset}\n`);
+
+        // Step 5: Update .env file
+        log('Step 5: Updating .env file...', 'bright');
 
         const envPath = path.join(__dirname, '..', '.env');
 
@@ -111,17 +118,14 @@ async function main() {
         // Read current .env file
         let envContent = fs.readFileSync(envPath, 'utf8');
 
-        // Escape backslashes and $ characters to prevent unintended interpolation in .env files
-        const escapedHash = hash.replace(/\\/g, '\\\\').replace(/\$/g, '\\$');
-
-        // Replace the hash line
+        // Replace the hash line with base64-encoded hash
         const hashRegex = /^MASTER_PASSWORD_BCRYPT_HASH=.*/m;
         if (hashRegex.test(envContent)) {
-            envContent = envContent.replace(hashRegex, `MASTER_PASSWORD_BCRYPT_HASH=${hash}`);
+            envContent = envContent.replace(hashRegex, `MASTER_PASSWORD_BCRYPT_HASH=${base64Hash}`);
             log('✓ Found and updated existing MASTER_PASSWORD_BCRYPT_HASH', 'green');
         } else {
             // Add it if it doesn't exist
-            envContent = `MASTER_PASSWORD_BCRYPT_HASH=${hash}\n` + envContent;
+            envContent = `MASTER_PASSWORD_BCRYPT_HASH=${base64Hash}\n` + envContent;
             log('✓ Added MASTER_PASSWORD_BCRYPT_HASH to .env', 'green');
         }
 

scripts/test-password.js

@@ -3,7 +3,7 @@
  *
  * Usage: node scripts/test-password.js "your-password"
  *
- * This will test your password against the hash in MASTER_PASSWORD_BCRYPT_HASH
+ * This will test your password against the base64-encoded hash in MASTER_PASSWORD_BCRYPT_HASH
  */
 
 const bcrypt = require('bcryptjs');
@@ -18,21 +18,27 @@ if (!password) {
     process.exit(1);
 }
 
-const hash = process.env.MASTER_PASSWORD_BCRYPT_HASH;
+const base64Hash = process.env.MASTER_PASSWORD_BCRYPT_HASH;
 
-if (!hash) {
+if (!base64Hash) {
     console.error('ERROR: MASTER_PASSWORD_BCRYPT_HASH not found in environment');
-    console.error('Make sure you have a .env.local file with MASTER_PASSWORD_BCRYPT_HASH set');
+    console.error('Make sure you have a .env file with MASTER_PASSWORD_BCRYPT_HASH set');
     process.exit(1);
 }
 
 console.log('Testing password...');
 console.log('Password length:', password.length);
 console.log('Password (first 3 chars):', password.substring(0, 3) + '***');
-console.log('Hash exists:', !!hash);
-console.log('Hash starts with $2:', hash.startsWith('$2'));
-console.log('Hash length:', hash.length);
-console.log('Hash format:', hash.substring(0, 7) + '...');
+console.log('Base64 hash exists:', !!base64Hash);
+console.log('Base64 hash length:', base64Hash.length);
+console.log('Base64 hash (first 20 chars):', base64Hash.substring(0, 20) + '...');
+
+// Decode the base64 hash
+const hash = Buffer.from(base64Hash, 'base64').toString('utf8');
+console.log('Decoded hash exists:', !!hash);
+console.log('Decoded hash starts with $2:', hash.startsWith('$2'));
+console.log('Decoded hash length:', hash.length);
+console.log('Decoded hash format:', hash.substring(0, 7) + '...');
 
 bcrypt.compare(password, hash).then(result => {
     console.log('\n' + '='.repeat(50));