feat(encryption): foundation package (Stage 0) (#719)

## Summary

Stage 0 of the data-at-rest encryption rollout from PR #707
(`docs/design/2026_04_29_proposed_data_at_rest_encryption.md`). This PR
is library-only — no integration with existing storage / raft / FSM
layers. Those land in Stages 1–9.

New package `internal/encryption/`:

- `cipher.go` — AES-256-GCM `Encrypt` / `Decrypt` primitive over a
`Keystore`. Caller-supplied AAD bytes (no AAD composition baked in —
storage and raft layers compose their own AAD per §4.1 / §4.2 in later
stages). `Decrypt` wraps GCM tag mismatch as `ErrIntegrity` with the
original `Open` error attached as a secondary cause, so callers match
via `errors.Is` and never silently zero or retry.
- `envelope.go` — §4.1 wire format encoder/decoder. Layout: `[version
1B][flag 1B][key_id 4B BE][nonce 12B][ciphertext+tag]`.
`EnvelopeOverhead = 34` bytes. `HeaderAADBytes` helper exposed for
storage callers that compose `AAD = HeaderAADBytes ‖ pebble_key`.
`ReservedKeyID = 0` sentinel per §5.1.
- `keystore.go` — copy-on-write `atomic.Pointer[map[uint32][]byte]` DEK
store. `Get` is a single atomic load (no mutex on the hot path per §10
self-review lens 2). `Set` rejects `ReservedKeyID` and non-32-byte DEKs;
copies input.
- `errors.go` — typed errors: `ErrUnknownKeyID`, `ErrReservedKeyID`,
`ErrBadNonceSize`, `ErrBadKeySize`, `ErrIntegrity`, `ErrEnvelopeShort`,
`ErrEnvelopeVersion`.
- `kek/kek.go` — `Wrapper` interface (`Wrap` / `Unwrap` / `Name`).
KMS-backed providers (AWS KMS, GCP KMS, Vault) come in Stage 9.
- `kek/file.go` — `FileWrapper`: AES-256-GCM under a 32-byte KEK read
from a file. Output `[12B nonce][32B ct][16B tag] = 60 bytes`. Validates
lengths instead of padding/truncating.

Tests:

- `cipher_test.go` — round-trip across plaintext/AAD shapes;
tag/AAD/ciphertext/nonce tamper rejected with `ErrIntegrity`; typed
error checks for reserved/bad-nonce/unknown-key cases; distinct nonces
produce distinct ciphertexts.
- `cipher_prop_test.go` — `pgregory.net/rapid` property tests for
arbitrary plaintext/AAD round-trip and single-bit AAD-flip rejection
(the §4.1 cut-and-paste defence property).
- `envelope_test.go` — encode/decode round-trip; under-length input
rejected; unknown version bytes rejected; decode does not alias input.
- `keystore_test.go` — Set/Get/Delete/IDs/Len; concurrent reader/writer
stress under `-race`.
- `kek/file_test.go` — round-trip; distinct Wrap nonces; bad-length
rejection; tag/nonce tamper rejected; missing file.

## Self-review (per CLAUDE.md 5 lenses)

1. **Data loss** — Pure library, no persistence yet. `ErrIntegrity`
always propagated. Round-trip property test guards envelope-format bugs.
2. **Concurrency** — `atomic.Pointer[map]` for keystore; concurrent
stress test under `-race`.
3. **Performance** — AES-NI via `crypto/aes`. No allocations beyond
per-call ciphertext buffer (sync.Pool optimisation deferred to
integration stages).
4. **Data consistency** — No MVCC/OCC interaction yet.
5. **Test coverage** — 23 unit tests + 2 property tests, `-race` clean,
0 lint issues against project `.golangci.yaml`.

## Test plan

- [x] `go test ./internal/encryption/...` (~14s)
- [x] `go test -race ./internal/encryption/...` (~65s)
- [x] `golangci-lint run ./internal/encryption/...` (0 issues)
- [ ] Reviewer: confirm `Cipher` API does not bake storage/raft AAD
assumptions in (§4.1 vs §4.2 layouts must remain orthogonal).
- [ ] Reviewer: confirm `ReservedKeyID = 0` is rejected at all entry
points (`Cipher.Encrypt`, `Cipher.Decrypt`, `Keystore.Set`).

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## New Features
* Added AES-256-GCM encryption support with envelope-based encryption
format
* Implemented key management system for secure encryption key handling
* Added file-based key encryption key (KEK) support for key wrapping and
unwrapping
* Introduced comprehensive error handling for encryption operations
including integrity verification

## Tests
* Added extensive unit, benchmark, and property-based tests for
encryption functionality

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: bootjp

internal/encryption/cipher.go

@@ -0,0 +1,121 @@
+package encryption
+
+import (
+	"crypto/cipher"
+
+	"github.com/cockroachdb/errors"
+)
+
+// Cipher is the AES-256-GCM primitive over a Keystore.
+//
+// Cipher does NOT compose AAD — callers in store/ (§4.1 AAD) and
+// internal/raftengine/etcd/ (§4.2 AAD) supply the full AAD bytes. This
+// keeps the cipher narrow and lets each layer choose the right AAD
+// without baking storage/raft assumptions into the foundation package.
+//
+// AES key expansion and GCM initialization happen once per DEK at
+// Keystore.Set time; the hot path only needs an atomic.Pointer load
+// and a Seal/Open call.
+//
+// The zero value is NOT safe to use: Encrypt/Decrypt return
+// ErrNilKeystore for a zero-value or nil Cipher rather than nil-deref
+// panicking. Always construct via NewCipher.
+type Cipher struct {
+	keystore *Keystore
+}
+
+// NewCipher returns a Cipher backed by ks.
+//
+// Returns ErrNilKeystore if ks is nil. Catching this at construction
+// time turns a wiring mistake into a typed error during process
+// startup or DEK rotation, rather than a nil-deref panic on the first
+// Encrypt/Decrypt — important for the dynamic dependency-wiring paths
+// where the encryption stack may be re-initialised after a sidecar
+// resync (§5.5) or rotation (§5.2).
+func NewCipher(ks *Keystore) (*Cipher, error) {
+	if ks == nil {
+		return nil, errors.WithStack(ErrNilKeystore)
+	}
+	return &Cipher{keystore: ks}, nil
+}
+
+// Encrypt produces (ciphertext ‖ tag) for plaintext under the DEK
+// identified by keyID and the supplied nonce. aad is treated verbatim.
+//
+// Constraints:
+//   - keyID must not be ReservedKeyID; otherwise ErrReservedKeyID.
+//   - nonce must be NonceSize bytes; otherwise ErrBadNonceSize.
+//   - keyID must be present in the Keystore; otherwise ErrUnknownKeyID.
+//
+// CRITICAL: callers MUST NOT reuse the same (keyID, nonce) pair with
+// any two distinct plaintexts. Nonce reuse under AES-GCM is
+// catastrophic: it leaks the XOR of the two plaintexts and enables
+// authentication-key recovery. The §4.1 storage-layer integration
+// uses the nonce construction (node_id ‖ local_epoch ‖ write_count)
+// to guarantee uniqueness by construction; do not substitute a
+// different nonce scheme in that layer without a corresponding
+// uniqueness proof. (For tests / benchmarks, fresh crypto/rand
+// nonces are perfectly safe.)
+//
+// The returned slice has length len(plaintext) + TagSize. It is
+// freshly allocated; the caller may retain it indefinitely.
+func (c *Cipher) Encrypt(plaintext, aad []byte, keyID uint32, nonce []byte) ([]byte, error) {
+	aead, err := c.aeadFor(keyID, nonce)
+	if err != nil {
+		return nil, err
+	}
+	return aead.Seal(nil, nonce, plaintext, aad), nil
+}
+
+// Decrypt verifies and decrypts (ciphertext ‖ tag) using the DEK
+// identified by keyID, the supplied nonce, and the same aad bytes that
+// were passed to Encrypt.
+//
+// On GCM tag mismatch, Decrypt returns an error wrapping ErrIntegrity.
+// Per §4.1, callers MUST treat this as a typed read error and never
+// silently zero or retry. The original Open error is attached as a
+// secondary cause for diagnostic logging.
+func (c *Cipher) Decrypt(ciphertextAndTag, aad []byte, keyID uint32, nonce []byte) ([]byte, error) {
+	aead, err := c.aeadFor(keyID, nonce)
+	if err != nil {
+		return nil, err
+	}
+	plaintext, err := aead.Open(nil, nonce, ciphertextAndTag, aad)
+	if err != nil {
+		// Wrap ErrIntegrity (the typed error callers match via errors.Is)
+		// and attach the original GCM Open error as a secondary cause for
+		// diagnostic logging. Per §4.1, callers MUST treat this as a
+		// typed read error and never silently zero or retry.
+		return nil, errors.Wrap(
+			errors.WithSecondaryError(ErrIntegrity, err),
+			"encryption: aead.Open",
+		)
+	}
+	return plaintext, nil
+}
+
+// aeadFor validates keyID and nonce length, then returns the
+// pre-initialized AEAD from the keystore. The hot path here is a single
+// atomic.Pointer load + a map lookup; AES key expansion happened once
+// at Keystore.Set time.
+//
+// A nil receiver or zero-value Cipher (i.e. c.keystore == nil) is
+// rejected with ErrNilKeystore so a caller that bypasses NewCipher and
+// uses var c encryption.Cipher gets a typed error instead of a
+// nil-deref panic on the first Encrypt/Decrypt.
+func (c *Cipher) aeadFor(keyID uint32, nonce []byte) (cipher.AEAD, error) {
+	if c == nil || c.keystore == nil {
+		return nil, errors.WithStack(ErrNilKeystore)
+	}
+	if keyID == ReservedKeyID {
+		return nil, errors.WithStack(ErrReservedKeyID)
+	}
+	if len(nonce) != NonceSize {
+		return nil, errors.Wrapf(ErrBadNonceSize, "got %d bytes, want %d", len(nonce), NonceSize)
+	}
+	aead, ok := c.keystore.AEAD(keyID)
+	if !ok {
+		return nil, errors.Wrapf(ErrUnknownKeyID, "key_id=%d", keyID)
+	}
+	return aead, nil
+}

internal/encryption/cipher_bench_test.go

@@ -0,0 +1,126 @@
+package encryption_test
+
+import (
+	"crypto/rand"
+	"strconv"
+	"testing"
+
+	"github.com/bootjp/elastickv/internal/encryption"
+)
+
+// benchPlaintextSizes covers the value-size range that storage / raft
+// envelopes hit on the hot path: small (Redis counters, SET keys),
+// medium (typical KV payloads, JSON), large (DynamoDB items, S3 small
+// objects). 64 KiB caps the upper end so the benchmark stays under a
+// few seconds; bigger plaintexts are AES-NI-bound and the per-byte
+// throughput is already extracted at 64 KiB.
+var benchPlaintextSizes = []int{64, 1024, 16 * 1024, 64 * 1024}
+
+func setupBench(b *testing.B) (*encryption.Cipher, uint32, []byte) {
+	b.Helper()
+	ks := encryption.NewKeystore()
+	dek := make([]byte, encryption.KeySize)
+	if _, err := rand.Read(dek); err != nil {
+		b.Fatalf("rand.Read dek: %v", err)
+	}
+	if err := ks.Set(testKeyID, dek); err != nil {
+		b.Fatalf("Set: %v", err)
+	}
+	c, err := encryption.NewCipher(ks)
+	if err != nil {
+		b.Fatalf("NewCipher: %v", err)
+	}
+	nonce := make([]byte, encryption.NonceSize)
+	if _, err := rand.Read(nonce); err != nil {
+		b.Fatalf("rand.Read nonce: %v", err)
+	}
+	return c, testKeyID, nonce
+}
+
+// BenchmarkCipher_Encrypt verifies the post-keystore-redesign hot path:
+// Set installed the AEAD once, so each Encrypt call should be a single
+// atomic.Pointer load + AEAD.Seal.
+func BenchmarkCipher_Encrypt(b *testing.B) {
+	c, keyID, nonce := setupBench(b)
+	aad := []byte("storage-aad-context")
+
+	for _, size := range benchPlaintextSizes {
+		plaintext := make([]byte, size)
+		if _, err := rand.Read(plaintext); err != nil {
+			b.Fatalf("rand.Read plaintext: %v", err)
+		}
+		b.Run(name(size), func(b *testing.B) {
+			b.SetBytes(int64(size))
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				if _, err := c.Encrypt(plaintext, aad, keyID, nonce); err != nil {
+					b.Fatal(err)
+				}
+			}
+		})
+	}
+}
+
+// BenchmarkCipher_Decrypt mirrors BenchmarkCipher_Encrypt for the read
+// side. Each iteration runs AEAD.Open against the same ciphertext so we
+// measure the steady-state cost rather than seeding overhead.
+func BenchmarkCipher_Decrypt(b *testing.B) {
+	c, keyID, nonce := setupBench(b)
+	aad := []byte("storage-aad-context")
+
+	for _, size := range benchPlaintextSizes {
+		plaintext := make([]byte, size)
+		if _, err := rand.Read(plaintext); err != nil {
+			b.Fatalf("rand.Read plaintext: %v", err)
+		}
+		ct, err := c.Encrypt(plaintext, aad, keyID, nonce)
+		if err != nil {
+			b.Fatalf("Encrypt: %v", err)
+		}
+		b.Run(name(size), func(b *testing.B) {
+			b.SetBytes(int64(size))
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				if _, err := c.Decrypt(ct, aad, keyID, nonce); err != nil {
+					b.Fatal(err)
+				}
+			}
+		})
+	}
+}
+
+// BenchmarkKeystore_AEAD exercises the hot-path lookup in isolation.
+// AEAD() should be a single atomic.Pointer load + map lookup; no
+// allocations, no per-call AES key expansion.
+func BenchmarkKeystore_AEAD(b *testing.B) {
+	ks := encryption.NewKeystore()
+	dek := make([]byte, encryption.KeySize)
+	if _, err := rand.Read(dek); err != nil {
+		b.Fatalf("rand.Read: %v", err)
+	}
+	if err := ks.Set(testKeyID, dek); err != nil {
+		b.Fatalf("Set: %v", err)
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, ok := ks.AEAD(testKeyID); !ok {
+			b.Fatal("AEAD lookup missed")
+		}
+	}
+}
+
+// name returns a sub-benchmark label scaling with size for readable
+// benchstat output ("64B", "1KiB", "16KiB", "64KiB").
+func name(size int) string {
+	switch {
+	case size < 1024:
+		return strconv.Itoa(size) + "B"
+	case size < 1024*1024:
+		return strconv.Itoa(size/1024) + "KiB"
+	default:
+		return strconv.Itoa(size/(1024*1024)) + "MiB"
+	}
+}

internal/encryption/cipher_prop_test.go

@@ -0,0 +1,103 @@
+package encryption_test
+
+import (
+	"bytes"
+	"crypto/rand"
+	"testing"
+
+	"github.com/bootjp/elastickv/internal/encryption"
+	"github.com/cockroachdb/errors"
+	"pgregory.net/rapid"
+)
+
+// TestCipher_RoundTripProperty checks that for arbitrary plaintext, AAD,
+// nonce, and key_id, Encrypt followed by Decrypt with the same inputs
+// recovers the exact plaintext. CLAUDE.md flags this kind of test as the
+// canonical safety net for envelope-format / compress-then-encrypt bugs.
+func TestCipher_RoundTripProperty(t *testing.T) {
+	rapid.Check(t, func(t *rapid.T) {
+		ks := encryption.NewKeystore()
+		// Random 32-byte DEK installed at a random non-reserved key_id.
+		dek := make([]byte, encryption.KeySize)
+		if _, err := rand.Read(dek); err != nil {
+			t.Fatalf("rand.Read dek: %v", err)
+		}
+		keyID := rapid.Uint32Range(1, 0xFFFFFFFF).Draw(t, "keyID")
+		if err := ks.Set(keyID, dek); err != nil {
+			t.Fatalf("ks.Set: %v", err)
+		}
+
+		c, err := encryption.NewCipher(ks)
+		if err != nil {
+			t.Fatalf("NewCipher: %v", err)
+		}
+		plaintext := rapid.SliceOfN(rapid.Byte(), 0, 4096).Draw(t, "plaintext")
+		aad := rapid.SliceOfN(rapid.Byte(), 0, 256).Draw(t, "aad")
+		nonce := make([]byte, encryption.NonceSize)
+		if _, err := rand.Read(nonce); err != nil {
+			t.Fatalf("rand.Read nonce: %v", err)
+		}
+
+		ct, err := c.Encrypt(plaintext, aad, keyID, nonce)
+		if err != nil {
+			t.Fatalf("Encrypt: %v", err)
+		}
+		got, err := c.Decrypt(ct, aad, keyID, nonce)
+		if err != nil {
+			t.Fatalf("Decrypt: %v", err)
+		}
+		// Both empty plaintext and empty got should compare equal; treat
+		// nil and empty as the same here so the property holds for the
+		// 0-length boundary.
+		if len(got) == 0 && len(plaintext) == 0 {
+			return
+		}
+		if !bytes.Equal(got, plaintext) {
+			t.Fatalf("plaintext mismatch:\n  got %x\n  want %x", got, plaintext)
+		}
+	})
+}
+
+// TestCipher_AADTamperProperty checks that any single-bit flip in the AAD
+// at decrypt time causes ErrIntegrity. This is the property that backs the
+// §4.1 cut-and-paste / blob-relocation defence.
+func TestCipher_AADTamperProperty(t *testing.T) {
+	rapid.Check(t, func(t *rapid.T) {
+		ks := encryption.NewKeystore()
+		dek := make([]byte, encryption.KeySize)
+		if _, err := rand.Read(dek); err != nil {
+			t.Fatalf("rand.Read dek: %v", err)
+		}
+		keyID := uint32(1)
+		if err := ks.Set(keyID, dek); err != nil {
+			t.Fatalf("ks.Set: %v", err)
+		}
+		c, err := encryption.NewCipher(ks)
+		if err != nil {
+			t.Fatalf("NewCipher: %v", err)
+		}
+
+		plaintext := rapid.SliceOfN(rapid.Byte(), 1, 256).Draw(t, "plaintext")
+		// AAD must be at least 1 byte so we can tamper.
+		aad := rapid.SliceOfN(rapid.Byte(), 1, 64).Draw(t, "aad")
+		nonce := make([]byte, encryption.NonceSize)
+		if _, err := rand.Read(nonce); err != nil {
+			t.Fatalf("rand.Read nonce: %v", err)
+		}
+
+		ct, err := c.Encrypt(plaintext, aad, keyID, nonce)
+		if err != nil {
+			t.Fatalf("Encrypt: %v", err)
+		}
+
+		idx := rapid.IntRange(0, len(aad)-1).Draw(t, "idx")
+		bit := rapid.Uint8Range(0, 7).Draw(t, "bit")
+		bad := append([]byte(nil), aad...)
+		bad[idx] ^= 1 << bit
+
+		_, err = c.Decrypt(ct, bad, keyID, nonce)
+		if !errors.Is(err, encryption.ErrIntegrity) {
+			t.Fatalf("expected ErrIntegrity for tampered AAD, got %v", err)
+		}
+	})
+}