Merge pull request #36 from ashioyajotham/fix/require-encryption-state-keys

fix(security): require ENCRYPTION_KEY and STATE_KEY at startup

Author: sangalo20

.env.example

@@ -11,10 +11,18 @@ BASE_URL=http://localhost:8080
 REDIRECT_PATH=/auth/callback
 REDIS_URL=redis://redis:6379
 
-# --- Security (REQUIRED: Change these for production!) ---
-# Generate new keys: openssl rand -base64 32
-ENCRYPTION_KEY=dGhpcy1pcy1hLXRlc3QtZW5jcnlwdGlvbi1rZXktMTI=
-STATE_KEY=dGhpcy1pcy1hLXRlc3Qtc3RhdGUta2V5LTEyMzQ1Njc=
+# --- Security (REQUIRED — services will refuse to start without these) ---
+
+# REQUIRED — 32-byte AES-256-GCM master key for encrypting stored tokens.
+# Generate with: openssl rand -base64 32
+# WARNING: If this key changes or is lost, all stored connections become
+# permanently unreadable. Back this up like a production secret.
+ENCRYPTION_KEY=
+
+# REQUIRED — 32-byte key for signing OAuth state parameters (CSRF prevention).
+# Must be identical on Broker and Gateway. Generate with: openssl rand -base64 32
+STATE_KEY=
+
 API_KEY=nexus-admin-key
 
 # --- Policies ---

docs/deployment.md

@@ -3,39 +3,47 @@
 ## Configuration
 
 ### Shared
-- `STATE_KEY` (base64‑32B): HMAC signing for `state` and nonce binding. **Must match between Gateway and Broker.**
+- `STATE_KEY` **(REQUIRED**, base64‑32B): HMAC signing for `state` and nonce binding. **Must match between Gateway and Broker.** Services will refuse to start if this is missing or invalid. Generate with `openssl rand -base64 32`.
 
 ### Broker (nexus-broker)
-Required for production:
+Required — the broker will not start without these:
 - `DATABASE_URL` (PostgreSQL connection string).
 - `BASE_URL` (Public URL, e.g., `https://broker.example.com`).
+- `ENCRYPTION_KEY` **(REQUIRED**, base64‑32B): AES‑GCM key for token encryption. **Must be stable.** If this key is lost, all stored connections become permanently unrecoverable. Generate with `openssl rand -base64 32`.
 - `REDIRECT_PATH` (Default `/auth/callback`).
-- `ENCRYPTION_KEY` (base64‑32B): AES‑GCM key for token encryption. **Must be stable.**
 - `API_KEY`: Key required for internal API access.
 - `ALLOWED_CIDRS`: Comma-separated list of allowed IP ranges (e.g., `10.0.0.0/8`).
 - `ALLOWED_RETURN_DOMAINS`: Comma-separated list of allowed domains for return URLs.
 
 ### Gateway (nexus-gateway)
 - `PORT`: Service port.
 - `BROKER_BASE_URL`: URL of the Broker (internal if possible).
-- `STATE_KEY`: Same as Broker.
+- `STATE_KEY` **(REQUIRED)**: Same as Broker — must match exactly.
 - `BROKER_API_KEY`: Key to authenticate with the Broker.
 
 ## Local Development (Quickstart)
 
+### 0. Generate required keys
+```bash
+# Run once, paste outputs into your .env file
+openssl rand -base64 32   # → ENCRYPTION_KEY
+openssl rand -base64 32   # → STATE_KEY (must be the same in Broker and Gateway)
+```
+
 ### 1. Run the Broker
 ```bash
+cp .env.example .env
+# Edit .env — fill in ENCRYPTION_KEY and STATE_KEY from step 0
 cd nexus-broker
-# Create a .env file based on .env.example
-source .env 
+source .env
 go run ./cmd/nexus-broker
 ```
 
 ### 2. Run the Gateway
 ```bash
 cd nexus-gateway
+source ../.env   # reuse the same STATE_KEY
 export BROKER_BASE_URL="http://localhost:8080"
-export STATE_KEY="$(openssl rand -base64 32)" # Use the same key as the Broker
 go run ./cmd/nexus-rest
 ```
 

nexus-broker/cmd/nexus-broker/main.go

@@ -2,15 +2,14 @@ package main
 
 import (
 	"context"
-	"crypto/rand"
-	"encoding/base64"
 	"log"
 	"net/url"
 	"os"
 	"strings"
 	"time"
 
 	"github.com/Prescott-Data/nexus-framework/nexus-broker/pkg/caching"
+	"github.com/Prescott-Data/nexus-framework/nexus-broker/pkg/config"
 	"github.com/Prescott-Data/nexus-framework/nexus-broker/pkg/handlers"
 	"github.com/Prescott-Data/nexus-framework/nexus-broker/pkg/provider"
 	"github.com/Prescott-Data/nexus-framework/nexus-broker/pkg/server"
@@ -45,43 +44,20 @@ func main() {
 		log.Fatal("BASE_URL environment variable is required")
 	}
 
-	// Setup encryption key (32 bytes for AES-256)
-	var encryptionKey []byte
-	if encryptionKeyStr != "" {
-		key, err := base64.StdEncoding.DecodeString(encryptionKeyStr)
-		if err != nil {
-			log.Fatal("Invalid ENCRYPTION_KEY format, must be base64 encoded")
-		}
-		if len(key) != 32 {
-			log.Fatal("ENCRYPTION_KEY must be 32 bytes (256 bits)")
-		}
-		encryptionKey = key
-	} else {
-		// Generate a random key for development
-		log.Println("WARNING: Using generated encryption key. Set ENCRYPTION_KEY environment variable for production.")
-		encryptionKey = make([]byte, 32)
-		if _, err := rand.Read(encryptionKey); err != nil {
-			log.Fatal("Failed to generate encryption key:", err)
-		}
+	// Validate required cryptographic keys — broker must not start without them.
+	// An ephemeral key would silently encrypt tokens that become unreadable on restart.
+	encryptionKey, err := config.ValidateKey("ENCRYPTION_KEY", encryptionKeyStr)
+	if err != nil {
+		log.Fatalf("Fatal configuration error: %v", err)
 	}
-
-	// Setup state signing key
-	var stateKey []byte
-	if stateKeyStr != "" {
-		key, err := base64.StdEncoding.DecodeString(stateKeyStr)
-		if err != nil {
-			log.Fatal("Invalid STATE_KEY format, must be base64 encoded")
-		}
-		stateKey = key
-	} else {
-		// Generate a random key for development
-		log.Println("WARNING: Using generated state key. Set STATE_KEY environment variable for production.")
-		stateKey = make([]byte, 32)
-		if _, err := rand.Read(stateKey); err != nil {
-			log.Fatal("Failed to generate state key:", err)
-		}
+	stateKey, err := config.ValidateKey("STATE_KEY", stateKeyStr)
+	if err != nil {
+		log.Fatalf("Fatal configuration error: %v", err)
 	}
 
+	log.Printf("ENCRYPTION_KEY fingerprint: %s", config.KeyFingerprint(encryptionKey))
+	log.Printf("STATE_KEY fingerprint: %s", config.KeyFingerprint(stateKey))
+
 	// Connect to database
 	db, err := sqlx.Connect("postgres", databaseURL)
 	if err != nil {

nexus-broker/pkg/config/keys.go

@@ -0,0 +1,50 @@
+package config
+
+import (
+	"encoding/base64"
+	"fmt"
+)
+
+// ValidateKey checks that a key value is set, valid base64, and decodes to
+// exactly 32 bytes (AES-256). Returns the decoded key or an error with an
+// actionable message including the environment variable name.
+func ValidateKey(envName, value string) ([]byte, error) {
+	if value == "" {
+		return nil, fmt.Errorf(
+			"%s is not set. "+
+				"This key is required and must be stable across restarts. "+
+				"Generate one with: openssl rand -base64 32",
+			envName,
+		)
+	}
+
+	decoded, err := base64.StdEncoding.DecodeString(value)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"%s is not valid base64: %w. "+
+				"Expected a base64-encoded 32-byte key. "+
+				"Generate one with: openssl rand -base64 32",
+			envName, err,
+		)
+	}
+
+	if len(decoded) != 32 {
+		return nil, fmt.Errorf(
+			"%s decoded to %d bytes, expected exactly 32. "+
+				"Generate a correct key with: openssl rand -base64 32",
+			envName, len(decoded),
+		)
+	}
+
+	return decoded, nil
+}
+
+// KeyFingerprint returns the first 8 characters of the base64-encoded key,
+// safe to log for diagnostics without exposing the full secret.
+func KeyFingerprint(key []byte) string {
+	encoded := base64.StdEncoding.EncodeToString(key)
+	if len(encoded) >= 8 {
+		return encoded[:8] + "..."
+	}
+	return encoded
+}

nexus-broker/pkg/config/keys_test.go

@@ -0,0 +1,95 @@
+package config
+
+import (
+	"crypto/rand"
+	"encoding/base64"
+	"strings"
+	"testing"
+)
+
+func validKey(t *testing.T) string {
+	t.Helper()
+	raw := make([]byte, 32)
+	if _, err := rand.Read(raw); err != nil {
+		t.Fatal(err)
+	}
+	return base64.StdEncoding.EncodeToString(raw)
+}
+
+func TestValidateKey_Valid(t *testing.T) {
+	encoded := validKey(t)
+	key, err := ValidateKey("TEST_KEY", encoded)
+	if err != nil {
+		t.Fatalf("expected no error, got: %v", err)
+	}
+	if len(key) != 32 {
+		t.Fatalf("expected 32 bytes, got %d", len(key))
+	}
+}
+
+func TestValidateKey_Empty(t *testing.T) {
+	_, err := ValidateKey("ENCRYPTION_KEY", "")
+	if err == nil {
+		t.Fatal("expected error for empty key")
+	}
+	if !strings.Contains(err.Error(), "ENCRYPTION_KEY is not set") {
+		t.Fatalf("error should mention env var name, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "openssl rand -base64 32") {
+		t.Fatalf("error should include generation hint, got: %v", err)
+	}
+}
+
+func TestValidateKey_InvalidBase64(t *testing.T) {
+	_, err := ValidateKey("STATE_KEY", "not!!valid!!base64$$")
+	if err == nil {
+		t.Fatal("expected error for invalid base64")
+	}
+	if !strings.Contains(err.Error(), "STATE_KEY is not valid base64") {
+		t.Fatalf("error should mention invalid base64, got: %v", err)
+	}
+}
+
+func TestValidateKey_WrongLength_Short(t *testing.T) {
+	short := base64.StdEncoding.EncodeToString(make([]byte, 16))
+	_, err := ValidateKey("ENCRYPTION_KEY", short)
+	if err == nil {
+		t.Fatal("expected error for 16-byte key")
+	}
+	if !strings.Contains(err.Error(), "16 bytes") {
+		t.Fatalf("error should report actual length, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "expected exactly 32") {
+		t.Fatalf("error should state expected length, got: %v", err)
+	}
+}
+
+func TestValidateKey_WrongLength_Long(t *testing.T) {
+	long := base64.StdEncoding.EncodeToString(make([]byte, 64))
+	_, err := ValidateKey("ENCRYPTION_KEY", long)
+	if err == nil {
+		t.Fatal("expected error for 64-byte key")
+	}
+	if !strings.Contains(err.Error(), "64 bytes") {
+		t.Fatalf("error should report actual length, got: %v", err)
+	}
+}
+
+func TestKeyFingerprint(t *testing.T) {
+	raw := make([]byte, 32)
+	for i := range raw {
+		raw[i] = byte(i)
+	}
+	fp := KeyFingerprint(raw)
+	encoded := base64.StdEncoding.EncodeToString(raw)
+
+	if !strings.HasPrefix(encoded, strings.TrimSuffix(fp, "...")) {
+		t.Fatalf("fingerprint %q should be prefix of full encoding %q", fp, encoded)
+	}
+	if !strings.HasSuffix(fp, "...") {
+		t.Fatalf("fingerprint should end with ellipsis, got: %q", fp)
+	}
+	if len(fp) != 11 { // 8 chars + "..."
+		t.Fatalf("fingerprint should be 11 chars (8 + ...), got %d: %q", len(fp), fp)
+	}
+}