Add secretbox for AES-256-GCM secrets at rest

internal/secretbox decodes the standard-base64 key from
MEALQUEST_SECRET_KEY_FILE, requires exactly 32 bytes, and seals secrets as
nonce ‖ ciphertext with a fresh random 12-byte nonce per call. Errors are
sentinels that never carry plaintext, ciphertext or key material.

The server builds the box before opening the database, so a non-base64 or
wrong-length key stops boot with an error naming the variable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cmd/server/boot_test.go

@@ -3,15 +3,21 @@ package main
 import (
 	"bytes"
 	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"errors"
 	"io/fs"
 	"log/slog"
-	"net/url"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"testing/fstest"
 	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/config"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
 
@@ -24,6 +30,37 @@ func useBootMigrations(t *testing.T, m fstest.MapFS) {
 	t.Cleanup(func() { bootMigrations = saved })
 }
 
+// loadConfig loads a configuration through config.Load whose secret key file
+// holds keyFile. Tests that call it must not run in parallel.
+func loadConfig(t *testing.T, keyFile string) config.Config {
+	t.Helper()
+	keyPath := filepath.Join(t.TempDir(), "secret_key")
+	if err := os.WriteFile(keyPath, []byte(keyFile), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv(config.EnvHTTPAddr, "127.0.0.1:0")
+	t.Setenv(config.EnvPublicURL, "http://localhost")
+	t.Setenv(config.EnvDataDir, t.TempDir())
+	t.Setenv(config.EnvShutdownTimeout, "1s")
+	t.Setenv(config.EnvSecretKeyFile, keyPath)
+	cfg, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	return cfg
+}
+
+// validKeyFile returns secret key file contents as written by the README:
+// base64 of 32 random bytes followed by a newline.
+func validKeyFile(t *testing.T) string {
+	t.Helper()
+	key := make([]byte, secretbox.KeySize)
+	if _, err := rand.Read(key); err != nil {
+		t.Fatal(err)
+	}
+	return base64.StdEncoding.EncodeToString(key) + "\n"
+}
+
 var brokenMigrations = fstest.MapFS{
 	"0000_good.sql":   {Data: []byte("CREATE TABLE good (id INTEGER PRIMARY KEY);")},
 	"0001_broken.sql": {Data: []byte("CREATE TABLE broken (id INTEGER PRIMARY KEY;")},
@@ -73,12 +110,7 @@ func TestRunMigrationFailureReturnsBeforeListening(t *testing.T) {
 	useBootMigrations(t, brokenMigrations)
 
 	var logs bytes.Buffer
-	cfg := config.Config{
-		HTTPAddr:        "127.0.0.1:0",
-		PublicURL:       &url.URL{Scheme: "http", Host: "localhost"},
-		DataDir:         t.TempDir(),
-		ShutdownTimeout: time.Second,
-	}
+	cfg := loadConfig(t, validKeyFile(t))
 	errc := make(chan error, 1)
 	go func() { errc <- run(cfg, slog.New(slog.NewJSONHandler(&logs, nil))) }()
 
@@ -94,3 +126,70 @@ func TestRunMigrationFailureReturnsBeforeListening(t *testing.T) {
 		t.Errorf("run started listening despite the migration failure: %s", logs.String())
 	}
 }
+
+func TestOpenSecretBoxAcceptsReadmeKey(t *testing.T) {
+	cfg := loadConfig(t, validKeyFile(t))
+	box, err := openSecretBox(cfg.SecretKey)
+	if err != nil {
+		t.Fatal(err)
+	}
+	token, err := box.Encrypt([]byte("x"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := box.Decrypt(token); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRunBadSecretKeyStopsBoot(t *testing.T) {
+	short := base64.StdEncoding.EncodeToString(make([]byte, 31))
+	tests := []struct {
+		name    string
+		keyFile string
+		want    error
+	}{
+		{"not base64", "this is not a base64 key!\n", secretbox.ErrKeyEncoding},
+		{"wrong length", short + "\n", secretbox.ErrKeyLength},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := loadConfig(t, tt.keyFile)
+			var logs bytes.Buffer
+			errc := make(chan error, 1)
+			go func() { errc <- run(cfg, slog.New(slog.NewJSONHandler(&logs, nil))) }()
+
+			var err error
+			select {
+			case err = <-errc:
+			case <-time.After(10 * time.Second):
+				t.Fatal("run kept going with a bad secret key")
+			}
+			if !errors.Is(err, tt.want) {
+				t.Fatalf("run error = %v, want %v", err, tt.want)
+			}
+			if !strings.Contains(err.Error(), config.EnvSecretKeyFile) {
+				t.Errorf("error does not name %s: %v", config.EnvSecretKeyFile, err)
+			}
+			if key := strings.TrimSpace(tt.keyFile); strings.Contains(err.Error(), key) {
+				t.Errorf("error leaks the key: %v", err)
+			}
+			if strings.Contains(logs.String(), `"listening"`) {
+				t.Errorf("run started listening despite the bad key: %s", logs.String())
+			}
+			if _, statErr := os.Stat(filepath.Join(cfg.DataDir, store.FileName)); !errors.Is(statErr, fs.ErrNotExist) {
+				t.Errorf("run opened the database before rejecting the key (stat: %v)", statErr)
+			}
+		})
+	}
+}
+
+func TestLoadMissingSecretKeyFileStopsBoot(t *testing.T) {
+	loadConfig(t, validKeyFile(t)) // sets every other variable
+	t.Setenv(config.EnvSecretKeyFile, filepath.Join(t.TempDir(), "missing"))
+	_, err := config.Load()
+	var cfgErr *config.Error
+	if !errors.As(err, &cfgErr) || !strings.Contains(err.Error(), config.EnvSecretKeyFile) {
+		t.Fatalf("Load error = %v, want a config error naming %s", err, config.EnvSecretKeyFile)
+	}
+}

cmd/server/main.go

@@ -15,6 +15,7 @@ import (
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/config"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/server"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
@@ -41,6 +42,10 @@ func run(cfg config.Config, logger *slog.Logger) error {
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 
+	if _, err := openSecretBox(cfg.SecretKey); err != nil {
+		return err
+	}
+
 	db, err := openStore(ctx, cfg.DataDir)
 	if err != nil {
 		return err
@@ -86,6 +91,16 @@ func run(cfg config.Config, logger *slog.Logger) error {
 	return nil
 }
 
+// openSecretBox builds the secret box from the configured key, naming the
+// variable whose file holds a bad key. The key itself is never reported.
+func openSecretBox(key config.Secret) (*secretbox.Box, error) {
+	box, err := secretbox.New(key.Reveal())
+	if err != nil {
+		return nil, fmt.Errorf("%s: %w", config.EnvSecretKeyFile, err)
+	}
+	return box, nil
+}
+
 // bootMigrations is the migration set applied at boot. Tests replace it to
 // prove a failing migration stops the boot.
 var bootMigrations fs.FS = migrations.FS

internal/secretbox/secretbox.go

@@ -0,0 +1,81 @@
+// Package secretbox encrypts secrets at rest with AES-256-GCM. It is the only
+// owner of secret encryption: every _ct column holds a token produced by
+// Box.Encrypt, laid out as nonce ‖ ciphertext.
+//
+// Errors from this package never contain plaintext, ciphertext or key
+// material.
+package secretbox
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"encoding/base64"
+	"errors"
+	"fmt"
+)
+
+// KeySize is the decoded key length in bytes (AES-256).
+const KeySize = 32
+
+var (
+	// ErrKeyEncoding means the key is not valid standard base64.
+	ErrKeyEncoding = errors.New("secretbox: key is not valid standard base64")
+	// ErrKeyLength means the decoded key is not exactly KeySize bytes.
+	ErrKeyLength = errors.New("secretbox: key must decode to exactly 32 bytes")
+	// ErrMalformed means a token is too short to hold a nonce and tag.
+	ErrMalformed = errors.New("secretbox: token is too short")
+	// ErrDecrypt means a token failed authentication: it was corrupted or
+	// sealed under a different key.
+	ErrDecrypt = errors.New("secretbox: token failed authentication")
+)
+
+// Box seals and opens secrets under one key. It is safe for concurrent use.
+type Box struct {
+	aead cipher.AEAD
+}
+
+// New returns a Box for encodedKey, the standard-base64 encoding of a
+// KeySize-byte key.
+func New(encodedKey string) (*Box, error) {
+	key, err := base64.StdEncoding.Strict().DecodeString(encodedKey)
+	if err != nil {
+		// The decoder's error is not wrapped: it describes the key's content.
+		return nil, ErrKeyEncoding
+	}
+	if len(key) != KeySize {
+		return nil, fmt.Errorf("%w, got %d", ErrKeyLength, len(key))
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf("secretbox: %w", err)
+	}
+	aead, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, fmt.Errorf("secretbox: %w", err)
+	}
+	return &Box{aead: aead}, nil
+}
+
+// Encrypt seals plaintext under a fresh random nonce and returns
+// nonce ‖ ciphertext.
+func (b *Box) Encrypt(plaintext []byte) ([]byte, error) {
+	nonce := make([]byte, b.aead.NonceSize(), b.aead.NonceSize()+len(plaintext)+b.aead.Overhead())
+	if _, err := rand.Read(nonce); err != nil {
+		return nil, fmt.Errorf("secretbox: generate nonce: %w", err)
+	}
+	return b.aead.Seal(nonce, nonce, plaintext, nil), nil
+}
+
+// Decrypt authenticates and opens a token produced by Encrypt.
+func (b *Box) Decrypt(token []byte) ([]byte, error) {
+	n := b.aead.NonceSize()
+	if len(token) < n+b.aead.Overhead() {
+		return nil, ErrMalformed
+	}
+	plaintext, err := b.aead.Open(nil, token[:n], token[n:], nil)
+	if err != nil {
+		return nil, ErrDecrypt
+	}
+	return plaintext, nil
+}

internal/secretbox/secretbox_test.go

@@ -0,0 +1,200 @@
+package secretbox
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/base64"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// newKey returns a fresh random key and its standard-base64 encoding.
+func newKey(t *testing.T) ([]byte, string) {
+	t.Helper()
+	key := make([]byte, KeySize)
+	if _, err := rand.Read(key); err != nil {
+		t.Fatal(err)
+	}
+	return key, base64.StdEncoding.EncodeToString(key)
+}
+
+func newBox(t *testing.T) (*Box, []byte, string) {
+	t.Helper()
+	key, encoded := newKey(t)
+	box, err := New(encoded)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return box, key, encoded
+}
+
+// assertNoLeak fails if err's message contains any of the secrets, either
+// raw or base64-encoded.
+func assertNoLeak(t *testing.T, err error, secrets ...[]byte) {
+	t.Helper()
+	msg := err.Error()
+	for _, s := range secrets {
+		if len(s) == 0 {
+			continue
+		}
+		for _, form := range []string{string(s), base64.StdEncoding.EncodeToString(s), base64.RawStdEncoding.EncodeToString(s)} {
+			if strings.Contains(msg, form) {
+				t.Errorf("error %q leaks secret material %q", msg, form)
+			}
+		}
+	}
+}
+
+func TestRoundTrip(t *testing.T) {
+	box, _, _ := newBox(t)
+	for _, plaintext := range [][]byte{
+		[]byte("ya29.oauth-refresh-token"),
+		{},
+		bytes.Repeat([]byte{0x00, 0xff}, 4096),
+	} {
+		token, err := box.Encrypt(plaintext)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(plaintext) > 0 && bytes.Contains(token, plaintext) {
+			t.Errorf("token contains the plaintext")
+		}
+		got, err := box.Decrypt(token)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !bytes.Equal(got, plaintext) {
+			t.Errorf("Decrypt = %q, want %q", got, plaintext)
+		}
+	}
+}
+
+func TestTokenLayout(t *testing.T) {
+	box, _, _ := newBox(t)
+	plaintext := []byte("secret")
+	token, err := box.Encrypt(plaintext)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// nonce (12) ‖ ciphertext (len(plaintext)) ‖ GCM tag (16).
+	if want := 12 + len(plaintext) + 16; len(token) != want {
+		t.Errorf("token length = %d, want %d", len(token), want)
+	}
+}
+
+func TestEncryptUsesFreshNonce(t *testing.T) {
+	box, _, _ := newBox(t)
+	plaintext := []byte("same plaintext")
+	a, err := box.Encrypt(plaintext)
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, err := box.Encrypt(plaintext)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if bytes.Equal(a, b) {
+		t.Fatal("two encryptions of the same plaintext are identical")
+	}
+	if bytes.Equal(a[:12], b[:12]) {
+		t.Error("two encryptions reused the same nonce")
+	}
+}
+
+func TestDecryptRejectsFlippedByte(t *testing.T) {
+	box, key, encoded := newBox(t)
+	plaintext := []byte("do-not-leak-me")
+	token, err := box.Encrypt(plaintext)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Flip one bit in every position: nonce, ciphertext and tag.
+	for i := range token {
+		tampered := bytes.Clone(token)
+		tampered[i] ^= 0x01
+		got, err := box.Decrypt(tampered)
+		if !errors.Is(err, ErrDecrypt) {
+			t.Fatalf("byte %d flipped: Decrypt = %q, %v; want ErrDecrypt", i, got, err)
+		}
+		if got != nil {
+			t.Errorf("byte %d flipped: Decrypt returned plaintext alongside the error", i)
+		}
+		assertNoLeak(t, err, plaintext, key, []byte(encoded), tampered)
+	}
+}
+
+func TestDecryptRejectsWrongKey(t *testing.T) {
+	box, key, encoded := newBox(t)
+	other, otherKey, otherEncoded := newBox(t)
+	plaintext := []byte("do-not-leak-me")
+	token, err := box.Encrypt(plaintext)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := other.Decrypt(token)
+	if !errors.Is(err, ErrDecrypt) {
+		t.Fatalf("Decrypt with wrong key = %q, %v; want ErrDecrypt", got, err)
+	}
+	assertNoLeak(t, err, plaintext, key, []byte(encoded), otherKey, []byte(otherEncoded), token)
+}
+
+func TestDecryptRejectsShortToken(t *testing.T) {
+	box, _, _ := newBox(t)
+	for _, n := range []int{0, 1, 12, 12 + 15} {
+		token := bytes.Repeat([]byte{0xab}, n)
+		if _, err := box.Decrypt(token); !errors.Is(err, ErrMalformed) {
+			t.Errorf("Decrypt(%d bytes) error = %v, want ErrMalformed", n, err)
+		}
+	}
+}
+
+func TestNewRejectsBadKey(t *testing.T) {
+	key, _ := newKey(t)
+	tests := []struct {
+		name    string
+		encoded string
+		want    error
+	}{
+		{"empty", "", ErrKeyLength},
+		{"not base64", "not*base64!" + strings.Repeat("A", 33), ErrKeyEncoding},
+		{"url-safe alphabet", strings.Repeat("_-", 22), ErrKeyEncoding},
+		{"unpadded", base64.RawStdEncoding.EncodeToString(key), ErrKeyEncoding},
+		{"raw key bytes", string(key), ErrKeyEncoding},
+		{"too short", base64.StdEncoding.EncodeToString(key[:31]), ErrKeyLength},
+		{"too long", base64.StdEncoding.EncodeToString(append(bytes.Clone(key), 0x00)), ErrKeyLength},
+		{"AES-128 length", base64.StdEncoding.EncodeToString(key[:16]), ErrKeyLength},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			box, err := New(tt.encoded)
+			if !errors.Is(err, tt.want) {
+				t.Fatalf("New error = %v, want %v", err, tt.want)
+			}
+			if box != nil {
+				t.Error("New returned a Box alongside the error")
+			}
+			assertNoLeak(t, err, key, []byte(tt.encoded))
+		})
+	}
+}
+
+func TestNewAcceptsBase64Key(t *testing.T) {
+	key, encoded := newKey(t)
+	box, err := New(encoded)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// A Box built from the same key opens tokens sealed by the first.
+	token, err := box.Encrypt([]byte("x"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	again, err := New(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := again.Decrypt(token); err != nil {
+		t.Errorf("same key failed to decrypt: %v", err)
+	}
+}