feat: Add SecretStore port and EnvSecretStore adapter (operational-gateway) (#1302)

* feat: Add SecretStore port and EnvSecretStore adapter for operational-gateway

Introduces the SecretStore port interface (ports.SecretStore) with
ErrSecretNotFound sentinel error, and a Phase 1 environment variable
adapter (adapters/secrets.EnvSecretStore).

The adapter resolves secrets using the convention:
  TENANT_{SLUG}_{SECRET_REF}
where slug and ref are uppercased with hyphens replaced by underscores.
A TenantSlugResolver interface decouples slug lookup from the adapter,
enabling test doubles and future caching without changing dispatch logic.

Secret values are never logged. Environment variables are intended to be
injected via Kubernetes Secrets.

* docs: Add docstrings to test functions for docstring coverage threshold

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

services/operational-gateway/adapters/secrets/env_secret_store.go

@@ -0,0 +1,80 @@
+// Package secrets provides adapters for resolving tenant secrets.
+package secrets
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/meridianhub/meridian/services/operational-gateway/ports"
+)
+
+// TenantSlugResolver looks up the human-readable slug for a tenant ID.
+// The slug is used to construct environment variable names so that secrets
+// are namespaced per tenant without embedding UUIDs in variable names.
+type TenantSlugResolver interface {
+	// GetSlug returns the slug for the given tenantID, e.g. "acme-corp".
+	// Returns an error if the tenant cannot be found or the lookup fails.
+	GetSlug(ctx context.Context, tenantID string) (string, error)
+}
+
+// EnvSecretStore resolves tenant secrets from environment variables.
+//
+// Environment variable naming convention:
+//
+//	TENANT_{SLUG}_{SECRET_REF}
+//
+// where SLUG and SECRET_REF are uppercased and hyphens are replaced with
+// underscores. For example, a tenant with slug "acme-corp" and secret
+// reference "STRIPE_API_KEY" resolves to:
+//
+//	TENANT_ACME_CORP_STRIPE_API_KEY
+//
+// This adapter is intended for Phase 1 deployments where secrets are
+// injected as environment variables via Kubernetes Secrets. For production
+// workloads at scale, replace this adapter with one backed by a secrets
+// manager (e.g. AWS SSM Parameter Store, HashiCorp Vault).
+//
+// Security note: secret values are never logged.
+type EnvSecretStore struct {
+	slugResolver TenantSlugResolver
+}
+
+// NewEnvSecretStore creates a new EnvSecretStore with the given slug resolver.
+func NewEnvSecretStore(resolver TenantSlugResolver) *EnvSecretStore {
+	return &EnvSecretStore{slugResolver: resolver}
+}
+
+// Resolve looks up the secret value from an environment variable.
+// It implements ports.SecretStore.
+//
+// Returns ports.ErrSecretNotFound if the environment variable is not set.
+// Returns a wrapped error if the slug resolver fails.
+func (s *EnvSecretStore) Resolve(ctx context.Context, tenantID, secretRef string) (string, error) {
+	slug, err := s.slugResolver.GetSlug(ctx, tenantID)
+	if err != nil {
+		return "", fmt.Errorf("failed to resolve slug for tenant %q: %w", tenantID, err)
+	}
+
+	envName := buildEnvName(slug, secretRef)
+
+	value, ok := os.LookupEnv(envName)
+	if !ok {
+		return "", fmt.Errorf("%w: %s", ports.ErrSecretNotFound, envName)
+	}
+
+	return value, nil
+}
+
+// buildEnvName constructs the environment variable name for a given tenant slug
+// and secret reference using the convention TENANT_{SLUG}_{SECRET_REF}.
+func buildEnvName(slug, secretRef string) string {
+	return "TENANT_" + toEnvName(slug) + "_" + toEnvName(secretRef)
+}
+
+// toEnvName normalises a string for use in an environment variable name:
+// uppercases all characters and replaces hyphens with underscores.
+func toEnvName(s string) string {
+	return strings.ToUpper(strings.ReplaceAll(s, "-", "_"))
+}

services/operational-gateway/adapters/secrets/env_secret_store_test.go

@@ -0,0 +1,121 @@
+package secrets_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/meridianhub/meridian/services/operational-gateway/adapters/secrets"
+	"github.com/meridianhub/meridian/services/operational-gateway/ports"
+)
+
+// staticSlugResolver returns a fixed slug for any tenant ID.
+type staticSlugResolver struct {
+	slug string
+	err  error
+}
+
+// GetSlug returns the configured slug and error for any input.
+func (r *staticSlugResolver) GetSlug(_ context.Context, _ string) (string, error) {
+	return r.slug, r.err
+}
+
+// errorSlugResolver always returns an error.
+type errorSlugResolver struct{ err error }
+
+// GetSlug always returns an empty slug and the configured error.
+func (r *errorSlugResolver) GetSlug(_ context.Context, _ string) (string, error) {
+	return "", r.err
+}
+
+// TestEnvSecretStore_Resolve_Success verifies that Resolve returns the correct secret value
+// when the environment variable is set and the slug resolver succeeds.
+func TestEnvSecretStore_Resolve_Success(t *testing.T) {
+	resolver := &staticSlugResolver{slug: "acme-corp"}
+	store := secrets.NewEnvSecretStore(resolver)
+
+	// env var name: TENANT_ACME_CORP_STRIPE_API_KEY
+	t.Setenv("TENANT_ACME_CORP_STRIPE_API_KEY", "sk_live_xyz")
+
+	got, err := store.Resolve(context.Background(), "tenant-001", "STRIPE_API_KEY")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "sk_live_xyz" {
+		t.Fatalf("expected %q, got %q", "sk_live_xyz", got)
+	}
+}
+
+// TestEnvSecretStore_Resolve_SecretNotFound verifies that Resolve returns ErrSecretNotFound
+// when no matching environment variable is set.
+func TestEnvSecretStore_Resolve_SecretNotFound(t *testing.T) {
+	resolver := &staticSlugResolver{slug: "acme"}
+	store := secrets.NewEnvSecretStore(resolver)
+
+	// No environment variable set for this secret.
+	_, err := store.Resolve(context.Background(), "tenant-001", "MISSING_SECRET")
+	if !errors.Is(err, ports.ErrSecretNotFound) {
+		t.Fatalf("expected ErrSecretNotFound, got: %v", err)
+	}
+}
+
+// TestEnvSecretStore_Resolve_SlugResolverError verifies that Resolve propagates and wraps
+// errors returned by the TenantSlugResolver.
+func TestEnvSecretStore_Resolve_SlugResolverError(t *testing.T) {
+	slugErr := errors.New("slug lookup failed")
+	resolver := &errorSlugResolver{err: slugErr}
+	store := secrets.NewEnvSecretStore(resolver)
+
+	_, err := store.Resolve(context.Background(), "tenant-001", "SOME_KEY")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !errors.Is(err, slugErr) {
+		t.Fatalf("expected wrapped slug error, got: %v", err)
+	}
+}
+
+// TestEnvSecretStore_Resolve_HyphensAndUnderscores verifies that hyphens in both the slug
+// and the secret reference are normalised to underscores when building the env var name.
+func TestEnvSecretStore_Resolve_HyphensAndUnderscores(t *testing.T) {
+	// Slugs with hyphens and secret refs with underscores should both normalise correctly.
+	// slug "my-tenant" → "MY_TENANT", ref "WEBHOOK_SECRET" → TENANT_MY_TENANT_WEBHOOK_SECRET
+	resolver := &staticSlugResolver{slug: "my-tenant"}
+	store := secrets.NewEnvSecretStore(resolver)
+
+	t.Setenv("TENANT_MY_TENANT_WEBHOOK_SECRET", "whsec_abc")
+
+	got, err := store.Resolve(context.Background(), "ignored", "WEBHOOK_SECRET")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "whsec_abc" {
+		t.Fatalf("expected %q, got %q", "whsec_abc", got)
+	}
+}
+
+// TestEnvSecretStore_Resolve_SecretRefWithHyphens verifies that a secret reference
+// containing hyphens is correctly normalised to underscores when building the env var name.
+func TestEnvSecretStore_Resolve_SecretRefWithHyphens(t *testing.T) {
+	// Secret references that contain hyphens should be normalised to underscores.
+	resolver := &staticSlugResolver{slug: "acme"}
+	store := secrets.NewEnvSecretStore(resolver)
+
+	// ref "stripe-api-key" → "STRIPE_API_KEY" → env var TENANT_ACME_STRIPE_API_KEY
+	t.Setenv("TENANT_ACME_STRIPE_API_KEY", "sk_test_321")
+
+	got, err := store.Resolve(context.Background(), "ignored", "stripe-api-key")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "sk_test_321" {
+		t.Fatalf("expected %q, got %q", "sk_test_321", got)
+	}
+}
+
+// TestNewEnvSecretStore_ImplementsSecretStore is a compile-time assertion that EnvSecretStore
+// satisfies the ports.SecretStore interface.
+func TestNewEnvSecretStore_ImplementsSecretStore(_ *testing.T) {
+	// Compile-time assertion: EnvSecretStore must satisfy the SecretStore port.
+	var _ ports.SecretStore = secrets.NewEnvSecretStore(&staticSlugResolver{})
+}

services/operational-gateway/ports/secret_store.go

@@ -0,0 +1,20 @@
+// Package ports defines the interfaces (ports) for the operational-gateway service.
+package ports
+
+import (
+	"context"
+	"errors"
+)
+
+// ErrSecretNotFound is returned when a secret cannot be found for the given tenant and reference.
+var ErrSecretNotFound = errors.New("secret not found")
+
+// SecretStore resolves tenant secrets by reference at dispatch time.
+// Implementations may read from environment variables, a secrets manager (e.g. AWS SSM,
+// HashiCorp Vault), or other backends. The interface is intentionally narrow so that
+// adapters can be swapped without changing the dispatch logic.
+type SecretStore interface {
+	// Resolve returns the plaintext secret value for the given tenant and secret reference.
+	// Returns ErrSecretNotFound if no value exists for the combination.
+	Resolve(ctx context.Context, tenantID, secretRef string) (string, error)
+}

services/operational-gateway/ports/secret_store_test.go

@@ -0,0 +1,68 @@
+package ports_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/meridianhub/meridian/services/operational-gateway/ports"
+)
+
+// stubSecretStore is a minimal in-test implementation used to verify the interface contract.
+type stubSecretStore struct {
+	secrets map[string]string
+}
+
+// Resolve returns the secret for the given tenant and ref, or ErrSecretNotFound.
+func (s *stubSecretStore) Resolve(_ context.Context, tenantID, secretRef string) (string, error) {
+	key := tenantID + ":" + secretRef
+	if v, ok := s.secrets[key]; ok {
+		return v, nil
+	}
+	return "", ports.ErrSecretNotFound
+}
+
+// TestSecretStore_Interface is a compile-time assertion that stubSecretStore
+// satisfies the SecretStore interface.
+func TestSecretStore_Interface(_ *testing.T) {
+	// Verify stubSecretStore satisfies the interface at compile time.
+	var _ ports.SecretStore = &stubSecretStore{}
+}
+
+// TestErrSecretNotFound_IsSentinel verifies that ErrSecretNotFound can be identified
+// via errors.Is for use in error handling chains.
+func TestErrSecretNotFound_IsSentinel(t *testing.T) {
+	err := ports.ErrSecretNotFound
+	if !errors.Is(err, ports.ErrSecretNotFound) {
+		t.Fatalf("expected ErrSecretNotFound to be detectable via errors.Is")
+	}
+}
+
+// TestSecretStore_Resolve_ReturnsValue verifies that Resolve returns the correct secret
+// value when the tenant and ref key combination exists.
+func TestSecretStore_Resolve_ReturnsValue(t *testing.T) {
+	store := &stubSecretStore{
+		secrets: map[string]string{
+			"tenant-abc:STRIPE_KEY": "sk_live_abc123",
+		},
+	}
+
+	got, err := store.Resolve(context.Background(), "tenant-abc", "STRIPE_KEY")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "sk_live_abc123" {
+		t.Fatalf("expected %q, got %q", "sk_live_abc123", got)
+	}
+}
+
+// TestSecretStore_Resolve_ReturnsErrSecretNotFound verifies that Resolve returns
+// ErrSecretNotFound when no secret exists for the given tenant and ref.
+func TestSecretStore_Resolve_ReturnsErrSecretNotFound(t *testing.T) {
+	store := &stubSecretStore{secrets: map[string]string{}}
+
+	_, err := store.Resolve(context.Background(), "tenant-abc", "MISSING_KEY")
+	if !errors.Is(err, ports.ErrSecretNotFound) {
+		t.Fatalf("expected ErrSecretNotFound, got: %v", err)
+	}
+}