feat(crypto): add per-page HPKE encryption for LTX v4

Implement per-page encryption using HPKE (RFC 9180) with
DHKEM(X25519) + HKDF-SHA256 + ChaCha20-Poly1305. Each LTX file
gets a random CEK wrapped per-recipient via HPKE, with separate
derived keys for page encryption and index authentication.

Key changes:
- Bump format to v4 with backward-compatible v3 decoding
- Add HeaderFlagEncryptedHPKE flag and encryption header fields
- Per-page ChaCha20-Poly1305 encryption with random nonces
- Page index authentication via AEAD with empty plaintext
- Duplicate recipient block at start and end for VFS access
- Multi-recipient support from day one
- CLI: keygen, rekey commands; -key/-encrypt-to flags on
  apply, dump, encode-db, list, verify

Refs #77

Author: corylanou

cmd/ltx/apply.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"encoding/hex"
 	"flag"
 	"fmt"
 	"io"
@@ -22,6 +23,7 @@ func NewApplyCommand() *ApplyCommand {
 func (c *ApplyCommand) Run(ctx context.Context, args []string) (ret error) {
 	fs := flag.NewFlagSet("ltx-apply", flag.ContinueOnError)
 	dbPath := fs.String("db", "", "database path")
+	keyHex := fs.String("key", "", "hex-encoded private key for decryption")
 	fs.Usage = func() {
 		fmt.Println(`
 The apply command applies one or more LTX files to a database file.
@@ -45,6 +47,15 @@ Arguments:
 		return fmt.Errorf("required: -db PATH")
 	}
 
+	var decryptionKey []byte
+	if *keyHex != "" {
+		var err error
+		decryptionKey, err = hex.DecodeString(*keyHex)
+		if err != nil {
+			return fmt.Errorf("invalid -key: %w", err)
+		}
+	}
+
 	// Open database file. Create if it doesn't exist.
 	dbFile, err := os.OpenFile(*dbPath, os.O_RDWR|os.O_CREATE, 0o666)
 	if err != nil {
@@ -54,7 +65,7 @@ Arguments:
 
 	// Apply LTX files in order.
 	for _, filename := range fs.Args() {
-		if err := c.applyLTXFile(ctx, dbFile, filename); err != nil {
+		if err := c.applyLTXFile(ctx, dbFile, filename, decryptionKey); err != nil {
 			return fmt.Errorf("%s: %s", filename, err)
 		}
 	}
@@ -66,7 +77,7 @@ Arguments:
 	return dbFile.Close()
 }
 
-func (c *ApplyCommand) applyLTXFile(_ context.Context, dbFile *os.File, filename string) error {
+func (c *ApplyCommand) applyLTXFile(_ context.Context, dbFile *os.File, filename string, decryptionKey []byte) error {
 	ltxFile, err := os.Open(filename)
 	if err != nil {
 		return err
@@ -75,6 +86,9 @@ func (c *ApplyCommand) applyLTXFile(_ context.Context, dbFile *os.File, filename
 
 	// Read LTX header and verify initial checksum matches.
 	dec := ltx.NewDecoder(ltxFile)
+	if decryptionKey != nil {
+		dec.SetDecryptionKey(decryptionKey)
+	}
 	if err := dec.DecodeHeader(); err != nil {
 		return fmt.Errorf("decode ltx header: %w", err)
 	}

cmd/ltx/dump.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"encoding/hex"
 	"flag"
 	"fmt"
 	"io"
@@ -22,6 +23,7 @@ func NewDumpCommand() *DumpCommand {
 // Run executes the command.
 func (c *DumpCommand) Run(ctx context.Context, args []string) (ret error) {
 	fs := flag.NewFlagSet("ltx-dump", flag.ContinueOnError)
+	keyHex := fs.String("key", "", "hex-encoded private key for decryption")
 	fs.Usage = func() {
 		fmt.Println(`
 The dump command writes out all data for a single LTX file.
@@ -43,13 +45,25 @@ Arguments:
 		return fmt.Errorf("too many arguments")
 	}
 
+	var decryptionKey []byte
+	if *keyHex != "" {
+		var err error
+		decryptionKey, err = hex.DecodeString(*keyHex)
+		if err != nil {
+			return fmt.Errorf("invalid -key: %w", err)
+		}
+	}
+
 	f, err := os.Open(fs.Arg(0))
 	if err != nil {
 		return err
 	}
 	defer func() { _ = f.Close() }()
 
 	dec := ltx.NewDecoder(f)
+	if decryptionKey != nil {
+		dec.SetDecryptionKey(decryptionKey)
+	}
 
 	// Read & print header information.
 	err = dec.DecodeHeader()
@@ -66,6 +80,12 @@ Arguments:
 	fmt.Printf("WAL offset: %d\n", hdr.WALOffset)
 	fmt.Printf("WAL size:   %d\n", hdr.WALSize)
 	fmt.Printf("WAL salt:   %08x %08x\n", hdr.WALSalt1, hdr.WALSalt2)
+	if hdr.Encrypted() {
+		fmt.Printf("Encrypted: yes (recipients=%d, KEM=0x%04x, KDF=0x%04x, AEAD=0x%04x)\n",
+			hdr.RecipientCount, hdr.KEMID, hdr.KDFID, hdr.AEADID)
+	} else {
+		fmt.Printf("Encrypted: no\n")
+	}
 	fmt.Printf("\n")
 	if err != nil {
 		return err

cmd/ltx/encode_db.go

@@ -4,10 +4,12 @@ import (
 	"bytes"
 	"context"
 	"encoding/binary"
+	"encoding/hex"
 	"flag"
 	"fmt"
 	"io"
 	"os"
+	"strings"
 	"time"
 
 	"github.com/superfly/ltx"
@@ -30,6 +32,7 @@ func NewEncodeDBCommand() *EncodeDBCommand {
 func (c *EncodeDBCommand) Run(ctx context.Context, args []string) (ret error) {
 	fs := flag.NewFlagSet("ltx-encode-db", flag.ContinueOnError)
 	outPath := fs.String("o", "", "output path")
+	encryptTo := fs.String("encrypt-to", "", "comma-separated hex-encoded public keys for encryption")
 	fs.Usage = func() {
 		fmt.Println(`
 The encode-db command encodes an SQLite database into an LTX file.
@@ -59,6 +62,17 @@ Arguments:
 	}
 	defer func() { _ = db.Close() }()
 
+	var recipientKeys [][]byte
+	if *encryptTo != "" {
+		for _, s := range strings.Split(*encryptTo, ",") {
+			key, err := hex.DecodeString(strings.TrimSpace(s))
+			if err != nil {
+				return fmt.Errorf("invalid -encrypt-to key: %w", err)
+			}
+			recipientKeys = append(recipientKeys, key)
+		}
+	}
+
 	out, err := os.OpenFile(*outPath, os.O_CREATE|os.O_WRONLY, 0o644)
 	if err != nil {
 		return fmt.Errorf("open output file: %w", err)
@@ -76,8 +90,13 @@ Arguments:
 	if err != nil {
 		return fmt.Errorf("create ltx encoder: %w", err)
 	}
+	if len(recipientKeys) > 0 {
+		if err := enc.SetEncryption(recipientKeys); err != nil {
+			return fmt.Errorf("set encryption: %w", err)
+		}
+	}
 	if err := enc.EncodeHeader(ltx.Header{
-		Version:   1,
+		Version:   ltx.Version,
 		Flags:     flags,
 		PageSize:  hdr.pageSize,
 		Commit:    hdr.pageN,

cmd/ltx/keygen.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"context"
+	"encoding/hex"
+	"flag"
+	"fmt"
+
+	"github.com/superfly/ltx"
+)
+
+type KeygenCommand struct{}
+
+func NewKeygenCommand() *KeygenCommand {
+	return &KeygenCommand{}
+}
+
+func (c *KeygenCommand) Run(_ context.Context, args []string) error {
+	fs := flag.NewFlagSet("ltx-keygen", flag.ContinueOnError)
+	fs.Usage = func() {
+		fmt.Println(`
+The keygen command generates an X25519 keypair for HPKE encryption.
+
+Usage:
+
+	ltx keygen
+
+Output is two lines of hex-encoded keys: public key, then private key.
+`[1:])
+	}
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+
+	pub, priv, err := ltx.GenerateKeyPair()
+	if err != nil {
+		return fmt.Errorf("generate keypair: %w", err)
+	}
+
+	fmt.Printf("public:  %s\n", hex.EncodeToString(pub))
+	fmt.Printf("private: %s\n", hex.EncodeToString(priv))
+
+	return nil
+}

cmd/ltx/list.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"encoding/hex"
 	"flag"
 	"fmt"
 	"io"
@@ -25,6 +26,7 @@ func NewListCommand() *ListCommand {
 func (c *ListCommand) Run(ctx context.Context, args []string) (ret error) {
 	fs := flag.NewFlagSet("ltx-list", flag.ContinueOnError)
 	tsv := fs.Bool("tsv", false, "output as tab-separated values")
+	keyHex := fs.String("key", "", "hex-encoded private key for decryption")
 	fs.Usage = func() {
 		fmt.Println(`
 The list command lists header & trailer information for a set of LTX files.
@@ -44,31 +46,43 @@ Arguments:
 		return fmt.Errorf("at least one LTX file is required")
 	}
 
+	var decryptionKey []byte
+	if *keyHex != "" {
+		var err error
+		decryptionKey, err = hex.DecodeString(*keyHex)
+		if err != nil {
+			return fmt.Errorf("invalid -key: %w", err)
+		}
+	}
+
 	var w io.Writer = os.Stdout
 	if !*tsv {
 		tw := tabwriter.NewWriter(os.Stdout, 0, 8, 2, ' ', 0)
 		defer func() { _ = tw.Flush() }()
 		w = tw
 	}
 
-	_, _ = fmt.Fprintln(w, "min_txid\tmax_txid\tcommit\tpages\tpreapply\tpostapply\ttimestamp\twal_offset\twal_size\twal_salt")
+	_, _ = fmt.Fprintln(w, "min_txid\tmax_txid\tcommit\tpages\tpreapply\tpostapply\ttimestamp\twal_offset\twal_size\twal_salt\tencrypted")
 	for _, arg := range fs.Args() {
-		if err := c.printFile(w, arg); err != nil {
+		if err := c.printFile(w, arg, decryptionKey); err != nil {
 			_, _ = fmt.Fprintf(os.Stderr, "%s: %s\n", arg, err)
 		}
 	}
 
 	return nil
 }
 
-func (c *ListCommand) printFile(w io.Writer, filename string) error {
+func (c *ListCommand) printFile(w io.Writer, filename string, decryptionKey []byte) error {
 	f, err := os.Open(filename)
 	if err != nil {
 		return err
 	}
 	defer func() { _ = f.Close() }()
 
 	dec := ltx.NewDecoder(f)
+	if decryptionKey != nil {
+		dec.SetDecryptionKey(decryptionKey)
+	}
 	if err := dec.Verify(); err != nil {
 		return err
 	}
@@ -79,7 +93,12 @@ func (c *ListCommand) printFile(w io.Writer, filename string) error {
 		timestamp = ""
 	}
 
-	_, _ = fmt.Fprintf(w, "%s\t%s\t%d\t%d\t%s\t%s\t%s\t%d\t%d\t%08x %08x\n",
+	encrypted := "no"
+	if dec.Header().Encrypted() {
+		encrypted = "yes"
+	}
+
+	_, _ = fmt.Fprintf(w, "%s\t%s\t%d\t%d\t%s\t%s\t%s\t%d\t%d\t%08x %08x\t%s\n",
 		dec.Header().MinTXID.String(),
 		dec.Header().MaxTXID.String(),
 		dec.Header().Commit,
@@ -90,6 +109,7 @@ func (c *ListCommand) printFile(w io.Writer, filename string) error {
 		dec.Header().WALOffset,
 		dec.Header().WALSize,
 		dec.Header().WALSalt1, dec.Header().WALSalt2,
+		encrypted,
 	)
 
 	return nil

cmd/ltx/main.go

@@ -49,8 +49,12 @@ func (m *Main) Run(ctx context.Context, args []string) (err error) {
 		return NewDumpCommand().Run(ctx, args)
 	case "encode-db":
 		return NewEncodeDBCommand().Run(ctx, args)
+	case "keygen":
+		return NewKeygenCommand().Run(ctx, args)
 	case "list":
 		return NewListCommand().Run(ctx, args)
+	case "rekey":
+		return NewRekeyCommand().Run(ctx, args)
 	case "verify":
 		return NewVerifyCommand().Run(ctx, args)
 	case "version":
@@ -85,7 +89,10 @@ The commands are:
 	apply        applies a set of LTX files to a database
 	checksum     computes the LTX checksum of a database file
 	dump         writes out metadata and page headers for a set of LTX files
+	encode-db    encodes an SQLite database into an LTX file
+	keygen       generates an X25519 keypair for HPKE encryption
 	list         lists header & trailer fields for LTX files in a table
+	rekey        re-encrypts an LTX file with new recipients
 	verify       reads & verifies checksums of a set of LTX files
 	version      prints the version
 `[1:])