feat: configugre regionkey provider

Author: alanshaw

config/config.go

@@ -1,6 +1,7 @@
 package config
 
 import (
+	"encoding/base64"
 	"errors"
 	"fmt"
 	"os"
@@ -95,6 +96,14 @@ type Config struct {
 	// (and Ship defaults to true) — e.g. to configure the catalog never to ship.
 	CatalogPlane PlaneSettings `mapstructure:"catalog_plane" yaml:"catalog_plane"`
 
+	// RegionKey selects and configures the region CEK wrap provider
+	// (regionkey.Provider): the component that wraps each object's
+	// content-encryption key under the region KEK for the read path (the
+	// FilOne encryption design's region wrap). Optional until the encrypting
+	// put/get paths are wired; anything consuming the provider fails at
+	// startup when it is unconfigured.
+	RegionKey RegionKeyConfig `mapstructure:"regionkey" yaml:"regionkey"`
+
 	// LogLevel is the zap level (debug|info|warn|error).
 	LogLevel string `mapstructure:"log_level" yaml:"log_level"`
 	// PostgresDSN is the registry/meta database.
@@ -224,6 +233,48 @@ type IdentityConfig struct {
 	KeyFile string `mapstructure:"key_file" yaml:"key_file"`
 }
 
+// RegionKeyConfig selects the region CEK wrap provider and carries each
+// implementation's settings.
+type RegionKeyConfig struct {
+	// Provider names the implementation: "openbao" (production — the wrap
+	// runs inside the region's OpenBao transit engine and the KEK never
+	// enters ingot's process) or "inprocess" (AES-256-GCM in ingot's own
+	// process; tests and development only). Empty means unconfigured.
+	Provider string `mapstructure:"provider" yaml:"provider"`
+	// OpenBao configures the "openbao" provider.
+	OpenBao OpenBaoConfig `mapstructure:"openbao" yaml:"openbao"`
+	// InProcess configures the "inprocess" provider.
+	InProcess InProcessConfig `mapstructure:"inprocess" yaml:"inprocess"`
+}
+
+// OpenBaoConfig is the "openbao" region-key provider's connection and key
+// settings.
+type OpenBaoConfig struct {
+	// Address of the OpenBao server, e.g. "https://bao.region.internal:8200"
+	// or a unix socket "unix:///run/openbao/api.sock". Empty falls back to
+	// the client's environment (BAO_ADDR, or upstream VAULT_ADDR).
+	Address string `mapstructure:"address" yaml:"address"`
+	// Token authenticates ingot to OpenBao; it needs encrypt/decrypt/rewrap
+	// on the transit key and nothing else. Empty falls back to the client's
+	// environment (BAO_TOKEN, or upstream VAULT_TOKEN).
+	Token string `mapstructure:"token" yaml:"token"`
+	// Mount is the transit engine's mount path. Empty means "transit".
+	Mount string `mapstructure:"mount" yaml:"mount"`
+	// Key is the transit key name holding the region KEK (provisioned with
+	// type aes256-gcm96 and derived=true). Required when provider=openbao.
+	Key string `mapstructure:"key" yaml:"key"`
+}
+
+// InProcessConfig is the "inprocess" region-key provider's settings.
+type InProcessConfig struct {
+	// KEK is the region key, base64-encoded 32 bytes. Empty generates a
+	// random key at startup — development only: wraps made under a generated
+	// key are unreadable after a restart.
+	KEK string `mapstructure:"kek" yaml:"kek"`
+	// Version tags wraps with the KEK's version. Empty means "v1".
+	Version string `mapstructure:"version" yaml:"version"`
+}
+
 // Load reads daemon config from configFile (or the default search path)
 // with env override (INGOT_* / nested keys via "_").
 func Load(configFile string) (*Config, error) {
@@ -263,6 +314,17 @@ func Load(configFile string) (*Config, error) {
 func setDefaults(v *viper.Viper) {
 	v.SetDefault("log_level", "info")
 	v.SetDefault("addr", "0.0.0.0:9000")
+	// The regionkey keys are registered even where the default is empty:
+	// viper's AutomaticEnv only overrides keys it already knows, so without
+	// these an INGOT_REGIONKEY_* env var would be silently ignored whenever
+	// the key is absent from the YAML.
+	v.SetDefault("regionkey.provider", "")
+	v.SetDefault("regionkey.openbao.address", "")
+	v.SetDefault("regionkey.openbao.token", "")
+	v.SetDefault("regionkey.openbao.mount", "transit")
+	v.SetDefault("regionkey.openbao.key", "")
+	v.SetDefault("regionkey.inprocess.kek", "")
+	v.SetDefault("regionkey.inprocess.version", "v1")
 }
 
 // Validate checks the config for the selected mode, aggregating every
@@ -308,6 +370,26 @@ func (c *Config) Validate() error {
 		errs = multierr.Append(errs, errors.New("revocation_service_url and revocation_service_did must be set together"))
 	}
 
+	switch c.RegionKey.Provider {
+	case "":
+		// Unconfigured is valid until the encrypting put/get paths are wired.
+	case "openbao":
+		if c.RegionKey.OpenBao.Key == "" {
+			errs = multierr.Append(errs, errors.New("regionkey.openbao.key (transit key name) is required when regionkey.provider is openbao"))
+		}
+	case "inprocess":
+		if c.RegionKey.InProcess.KEK != "" {
+			kek, err := base64.StdEncoding.DecodeString(c.RegionKey.InProcess.KEK)
+			if err != nil {
+				errs = multierr.Append(errs, fmt.Errorf("regionkey.inprocess.kek: %w", err))
+			} else if len(kek) != 32 {
+				errs = multierr.Append(errs, fmt.Errorf("regionkey.inprocess.kek must decode to 32 bytes (AES-256), got %d", len(kek)))
+			}
+		}
+	default:
+		errs = multierr.Append(errs, fmt.Errorf("regionkey.provider %q is not one of openbao, inprocess", c.RegionKey.Provider))
+	}
+
 	if errs != nil {
 		return fmt.Errorf("invalid config: %w", errs)
 	}

config/config_test.go

@@ -1,6 +1,7 @@
 package config
 
 import (
+	"encoding/base64"
 	"os"
 	"path/filepath"
 	"strings"
@@ -56,6 +57,16 @@ func TestValidate_RequiredFields(t *testing.T) {
 		{"revocation did without url", func(c *Config) { c.RevocationServiceDID = "did:web:swarf.example" }, "revocation_service_url and revocation_service_did must be set together"},
 		{"bad seal_age", func(c *Config) { c.SealAge = "not-a-duration" }, "parse seal_age"},
 		{"bad cors origin", func(c *Config) { c.CORSAllowedOrigins = []string{"app.example"} }, "cors_allowed_origins"},
+		{"unknown regionkey provider", func(c *Config) { c.RegionKey.Provider = "hsm" }, `regionkey.provider "hsm" is not one of openbao, inprocess`},
+		{"openbao without key", func(c *Config) { c.RegionKey.Provider = "openbao" }, "regionkey.openbao.key"},
+		{"inprocess kek not base64", func(c *Config) {
+			c.RegionKey.Provider = "inprocess"
+			c.RegionKey.InProcess.KEK = "not-base64!!"
+		}, "regionkey.inprocess.kek"},
+		{"inprocess kek wrong length", func(c *Config) {
+			c.RegionKey.Provider = "inprocess"
+			c.RegionKey.InProcess.KEK = "c2hvcnQ=" // "short"
+		}, "must decode to 32 bytes"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -80,6 +91,31 @@ func TestValidate_RevocationServicePair(t *testing.T) {
 	}
 }
 
+// TestValidate_RegionKey: both providers validate with their required
+// settings present; unconfigured (empty provider) stays valid until the
+// encrypting paths are wired.
+func TestValidate_RegionKey(t *testing.T) {
+	cfg := validConfig(t)
+	cfg.RegionKey.Provider = "openbao"
+	cfg.RegionKey.OpenBao.Key = "region-kek"
+	if err := cfg.Validate(); err != nil {
+		t.Fatalf("expected valid openbao regionkey config, got: %v", err)
+	}
+
+	cfg = validConfig(t)
+	cfg.RegionKey.Provider = "inprocess"
+	cfg.RegionKey.InProcess.KEK = base64.StdEncoding.EncodeToString(make([]byte, 32))
+	if err := cfg.Validate(); err != nil {
+		t.Fatalf("expected valid inprocess regionkey config, got: %v", err)
+	}
+
+	cfg = validConfig(t)
+	cfg.RegionKey.Provider = "inprocess" // empty KEK: generated at startup
+	if err := cfg.Validate(); err != nil {
+		t.Fatalf("expected valid inprocess config with no KEK, got: %v", err)
+	}
+}
+
 // TestValidate_AuthServiceProofs: the optional proofs value is loaded eagerly
 // so a bad path or encoding fails at startup.
 func TestValidate_AuthServiceProofs(t *testing.T) {

module.go

@@ -44,6 +44,8 @@ package ingot
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/base64"
 	"fmt"
 	"net/url"
 
@@ -53,6 +55,7 @@ import (
 	"github.com/fil-forge/ucantone/ucan"
 	"github.com/fil-forge/versitygw/auth"
 	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/openbao/openbao/api/v2"
 	"go.uber.org/fx"
 	"go.uber.org/zap"
 
@@ -64,6 +67,7 @@ import (
 	"github.com/fil-forge/ingot/iam"
 	"github.com/fil-forge/ingot/logstore"
 	"github.com/fil-forge/ingot/migrations"
+	"github.com/fil-forge/ingot/regionkey"
 	"github.com/fil-forge/ingot/registry"
 	"github.com/fil-forge/ingot/revocation"
 	"github.com/fil-forge/ingot/tokenstore"
@@ -112,6 +116,7 @@ func Module(cfg config.Config) fx.Option {
 			provideKeyProofs,
 			provideVerificationKeyCache,
 			provideIAMService,
+			provideRegionKeyProvider,
 			fx.Annotate(bucketauthority.New, fx.As(new(bucketauthority.BucketAuthority))),
 		),
 		ServerModule,
@@ -286,6 +291,54 @@ func provideAuthServiceClient(cfg config.Config, id ServiceIdentity, logger *zap
 	return hiltclient.New(authServiceDID, *authServiceURL, id.Signer, hiltclient.WithBaseProofs(proofs), hiltclient.WithLogger(logger))
 }
 
+// provideRegionKeyProvider builds the configured region CEK wrap provider
+// (config `regionkey.provider`): "openbao" runs the wrap inside the region's
+// OpenBao transit engine (the production choice — the region KEK never enters
+// this process), "inprocess" wraps with AES-256-GCM in process (tests and
+// development). The provider is lazy, so an unconfigured region key only
+// errors if a consumer actually needs it.
+func provideRegionKeyProvider(cfg config.Config, logger *zap.Logger) (regionkey.Provider, error) {
+	switch cfg.RegionKey.Provider {
+	case "openbao":
+		bao := cfg.RegionKey.OpenBao
+		apiCfg := api.DefaultConfig() // reads BAO_ADDR etc. from the environment
+		if bao.Address != "" {
+			apiCfg.Address = bao.Address
+		}
+		client, err := api.NewClient(apiCfg) // reads BAO_TOKEN from the environment
+		if err != nil {
+			return nil, fmt.Errorf("ingot: regionkey.openbao: %w", err)
+		}
+		if bao.Token != "" {
+			client.SetToken(bao.Token)
+		}
+		return regionkey.NewOpenBaoProvider(client, bao.Mount, bao.Key)
+	case "inprocess":
+		inproc := cfg.RegionKey.InProcess
+		var kek []byte
+		if inproc.KEK != "" {
+			var err error
+			kek, err = base64.StdEncoding.DecodeString(inproc.KEK)
+			if err != nil {
+				return nil, fmt.Errorf("ingot: regionkey.inprocess.kek: %w", err)
+			}
+		} else {
+			kek = make([]byte, regionkey.KEKLen)
+			if _, err := rand.Read(kek); err != nil {
+				return nil, fmt.Errorf("ingot: regionkey.inprocess: generating KEK: %w", err)
+			}
+			logger.Warn("regionkey: inprocess provider generated a random KEK; " +
+				"wrapped CEKs will be unreadable after a restart — set regionkey.inprocess.kek to persist one (development only)")
+		}
+		version := regionkey.KeyVersion(config.EmptyDefault(inproc.Version, "v1"))
+		return regionkey.NewInProcessProvider(version, kek)
+	case "":
+		return nil, fmt.Errorf("ingot: regionkey.provider is not configured")
+	default:
+		return nil, fmt.Errorf("ingot: regionkey.provider %q is not one of openbao, inprocess", cfg.RegionKey.Provider)
+	}
+}
+
 // provideKeyProofs is the per-access-key delegation store registry: the IAM
 // service deposits each key's Hilt-issued chains into its own store and
 // stashes that store on the request context, from which the network read

regionkey_provider_internal_test.go

@@ -0,0 +1,103 @@
+package ingot
+
+import (
+	"context"
+	"encoding/base64"
+	"testing"
+
+	"github.com/fil-forge/libforge/testutil"
+	"github.com/multiformats/go-multihash"
+	"go.uber.org/zap"
+
+	"github.com/fil-forge/ingot/config"
+	"github.com/fil-forge/ingot/regionkey"
+)
+
+// regionKeyCfg wraps a RegionKeyConfig into the minimal Config the provider
+// constructor reads.
+func regionKeyCfg(rk config.RegionKeyConfig) config.Config {
+	return config.Config{RegionKey: rk}
+}
+
+// TestProvideRegionKeyProvider_InProcess: the "inprocess" provider constructs
+// from a configured KEK and round-trips a wrap, proving the config path feeds
+// regionkey correctly end to end.
+func TestProvideRegionKeyProvider_InProcess(t *testing.T) {
+	kek := make([]byte, regionkey.KEKLen)
+	kek[0] = 0xAB
+	p, err := provideRegionKeyProvider(regionKeyCfg(config.RegionKeyConfig{
+		Provider:  "inprocess",
+		InProcess: config.InProcessConfig{KEK: base64.StdEncoding.EncodeToString(kek), Version: "v7"},
+	}), zap.NewNop())
+	if err != nil {
+		t.Fatalf("provideRegionKeyProvider: %v", err)
+	}
+
+	digest, err := multihash.Sum([]byte("blob-1"), multihash.SHA2_256, -1)
+	if err != nil {
+		t.Fatalf("multihash: %v", err)
+	}
+	binding := regionkey.BindingContext{Space: testutil.RandomDID(t), Digest: digest}
+	cek := []byte("0123456789abcdef0123456789abcdef")
+
+	wrapped, err := p.Wrap(context.Background(), binding, cek)
+	if err != nil {
+		t.Fatalf("Wrap: %v", err)
+	}
+	if wrapped.Version != "v7" {
+		t.Fatalf("Version = %q, want the configured v7", wrapped.Version)
+	}
+	got, err := p.Unwrap(context.Background(), binding, wrapped)
+	if err != nil {
+		t.Fatalf("Unwrap: %v", err)
+	}
+	if string(got) != string(cek) {
+		t.Fatalf("round-trip mismatch")
+	}
+}
+
+// An empty KEK generates one at startup (development): the provider works,
+// the wraps just die with the process.
+func TestProvideRegionKeyProvider_InProcessGeneratedKEK(t *testing.T) {
+	p, err := provideRegionKeyProvider(regionKeyCfg(config.RegionKeyConfig{Provider: "inprocess"}), zap.NewNop())
+	if err != nil {
+		t.Fatalf("provideRegionKeyProvider: %v", err)
+	}
+	wrapped, err := p.Wrap(context.Background(), regionkey.BindingContext{}, []byte("a 32-byte content encryption k."))
+	if err != nil {
+		t.Fatalf("Wrap: %v", err)
+	}
+	if wrapped.Version != "v1" {
+		t.Fatalf("Version = %q, want the default v1", wrapped.Version)
+	}
+}
+
+// TestProvideRegionKeyProvider_OpenBao: with a key configured the provider
+// constructs (no connection is made until the first wrap); without one it
+// fails.
+func TestProvideRegionKeyProvider_OpenBao(t *testing.T) {
+	if _, err := provideRegionKeyProvider(regionKeyCfg(config.RegionKeyConfig{
+		Provider: "openbao",
+		OpenBao:  config.OpenBaoConfig{Address: "http://127.0.0.1:8200", Key: "region-kek"},
+	}), zap.NewNop()); err != nil {
+		t.Fatalf("provideRegionKeyProvider: %v", err)
+	}
+	if _, err := provideRegionKeyProvider(regionKeyCfg(config.RegionKeyConfig{Provider: "openbao"}), zap.NewNop()); err == nil {
+		t.Fatal("expected an error with no transit key configured")
+	}
+}
+
+func TestProvideRegionKeyProvider_Selection(t *testing.T) {
+	if _, err := provideRegionKeyProvider(regionKeyCfg(config.RegionKeyConfig{}), zap.NewNop()); err == nil {
+		t.Fatal("expected an error for an unconfigured provider")
+	}
+	if _, err := provideRegionKeyProvider(regionKeyCfg(config.RegionKeyConfig{Provider: "hsm"}), zap.NewNop()); err == nil {
+		t.Fatal("expected an error for an unknown provider")
+	}
+	if _, err := provideRegionKeyProvider(regionKeyCfg(config.RegionKeyConfig{
+		Provider:  "inprocess",
+		InProcess: config.InProcessConfig{KEK: "not-base64!!"},
+	}), zap.NewNop()); err == nil {
+		t.Fatal("expected an error for a malformed KEK")
+	}
+}