Add factory helpers for user and scoped secret providers (#4242)

* Add CreateUserSecretProvider and CreateScopedSecretProvider factory helpers

Expose convenience constructors that wrap the base secret provider in either
a UserProvider (blocks system-reserved __thv_ keys for user-facing callers)
or a ScopedProvider (namespaces all operations under a given scope for
internal callers such as the registry or workloads subsystems).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Use t.Context() instead of context.Background() in factory tests

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update CreateScopedSecretProvider to use SecretScope type

Follow-up from the SecretScope type change: update the factory helper
signature to accept SecretScope instead of string.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Replace separate factory helpers with functional options on CreateProvider

Replace CreateUserSecretProvider and CreateScopedSecretProvider with a
single CreateProvider function that accepts ProviderOptions, consistent
with the functional options pattern already used in config_builder.go.

- Add ProviderOption type with WithUserFacing() and WithScope(scope)
- Validate mutual exclusivity: combining both options returns an error
- Without options, CreateProvider behaves like CreateSecretProvider
- Update tests to cover the new API and the mutual exclusion invariant

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: amirejaz

pkg/secrets/factory.go

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
 package secrets
@@ -271,6 +271,69 @@ func CreateSecretProviderWithPassword(managerType ProviderType, password string)
 	return primary, nil
 }
 
+// ProviderOption configures how CreateProvider wraps the underlying provider.
+type ProviderOption func(*providerOptions) error
+
+// providerOptions holds the accumulated state of all ProviderOptions passed to CreateProvider.
+type providerOptions struct {
+	scope      *SecretScope // nil = no scoping
+	userFacing bool
+}
+
+// WithScope returns a ProviderOption that wraps the provider with a ScopedProvider
+// for the given scope, keeping system secrets isolated under "__thv_<scope>_".
+// Mutually exclusive with WithUserFacing.
+func WithScope(scope SecretScope) ProviderOption {
+	return func(o *providerOptions) error {
+		if o.userFacing {
+			return errors.New("WithScope and WithUserFacing are mutually exclusive")
+		}
+		o.scope = &scope
+		return nil
+	}
+}
+
+// WithUserFacing returns a ProviderOption that wraps the provider with a UserProvider,
+// blocking access to any key that starts with the system prefix "__thv_".
+// Suitable for CLI, API, and MCP tool server callers.
+// Mutually exclusive with WithScope.
+func WithUserFacing() ProviderOption {
+	return func(o *providerOptions) error {
+		if o.scope != nil {
+			return errors.New("WithUserFacing and WithScope are mutually exclusive")
+		}
+		o.userFacing = true
+		return nil
+	}
+}
+
+// CreateProvider creates a secret Provider for the given manager type, optionally
+// wrapped according to the supplied options.
+//
+// Without options it behaves identically to CreateSecretProvider.
+// Pass WithUserFacing() for CLI/API callers or WithScope(scope) for internal callers.
+func CreateProvider(managerType ProviderType, opts ...ProviderOption) (Provider, error) {
+	inner, err := CreateSecretProvider(managerType)
+	if err != nil {
+		return nil, err
+	}
+
+	options := &providerOptions{}
+	for _, opt := range opts {
+		if err := opt(options); err != nil {
+			return nil, err
+		}
+	}
+
+	if options.userFacing {
+		return NewUserProvider(inner), nil
+	}
+	if options.scope != nil {
+		return NewScopedProvider(inner, *options.scope), nil
+	}
+	return inner, nil
+}
+
 // shouldEnableFallback determines if environment variable fallback should be enabled
 func shouldEnableFallback() bool {
 	// Check for explicit opt-out

pkg/secrets/factory_test.go

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
 package secrets_test
@@ -112,3 +112,85 @@ func TestEnvVarPrefix(t *testing.T) { //nolint:paralleltest
 		assert.Equal(t, "TOOLHIVE_SECRET_", secrets.EnvVarPrefix)
 	})
 }
+
+func TestCreateProvider_WithUserFacing(t *testing.T) { //nolint:paralleltest
+	t.Run("environment provider returns user provider", func(t *testing.T) { //nolint:paralleltest
+		provider, err := secrets.CreateProvider(secrets.EnvironmentType, secrets.WithUserFacing())
+		require.NoError(t, err)
+		require.NotNil(t, provider)
+
+		// UserProvider inherits read-only capabilities from the environment provider
+		caps := provider.Capabilities()
+		assert.True(t, caps.CanRead)
+		assert.False(t, caps.CanWrite)
+	})
+
+	t.Run("blocks system-reserved keys", func(t *testing.T) { //nolint:paralleltest
+		provider, err := secrets.CreateProvider(secrets.EnvironmentType, secrets.WithUserFacing())
+		require.NoError(t, err)
+
+		_, err = provider.GetSecret(t.Context(), "__thv_registry_foo")
+		require.ErrorIs(t, err, secrets.ErrReservedKeyName)
+	})
+
+	t.Run("allows non-system keys", func(t *testing.T) { //nolint:paralleltest
+		provider, err := secrets.CreateProvider(secrets.EnvironmentType, secrets.WithUserFacing())
+		require.NoError(t, err)
+
+		// A regular key should not be blocked (may return not-found, but not ErrReservedKeyName)
+		_, err = provider.GetSecret(t.Context(), "my-api-key")
+		require.NotErrorIs(t, err, secrets.ErrReservedKeyName)
+	})
+
+	t.Run("unknown provider returns error", func(t *testing.T) { //nolint:paralleltest
+		provider, err := secrets.CreateProvider(secrets.ProviderType("unknown"), secrets.WithUserFacing())
+		assert.Error(t, err)
+		assert.Nil(t, provider)
+	})
+}
+
+func TestCreateProvider_WithScope(t *testing.T) { //nolint:paralleltest
+	t.Run("environment provider returns scoped provider", func(t *testing.T) { //nolint:paralleltest
+		provider, err := secrets.CreateProvider(secrets.EnvironmentType, secrets.WithScope(secrets.ScopeRegistry))
+		require.NoError(t, err)
+		require.NotNil(t, provider)
+
+		// ScopedProvider inherits read-only capabilities from the environment provider
+		caps := provider.Capabilities()
+		assert.True(t, caps.CanRead)
+		assert.False(t, caps.CanWrite)
+	})
+
+	t.Run("scopes key access to given scope", func(t *testing.T) { //nolint:paralleltest
+		provider, err := secrets.CreateProvider(secrets.EnvironmentType, secrets.WithScope(secrets.ScopeRegistry))
+		require.NoError(t, err)
+
+		// Any get on an environment provider will return not-found; the key must not be blocked
+		_, err = provider.GetSecret(t.Context(), "my-token")
+		require.NotErrorIs(t, err, secrets.ErrReservedKeyName)
+	})
+
+	t.Run("unknown provider returns error", func(t *testing.T) { //nolint:paralleltest
+		provider, err := secrets.CreateProvider(secrets.ProviderType("unknown"), secrets.WithScope(secrets.ScopeRegistry))
+		assert.Error(t, err)
+		assert.Nil(t, provider)
+	})
+}
+
+func TestCreateProvider_MutualExclusion(t *testing.T) { //nolint:paralleltest
+	t.Run("WithScope and WithUserFacing are mutually exclusive", func(t *testing.T) { //nolint:paralleltest
+		_, err := secrets.CreateProvider(secrets.EnvironmentType,
+			secrets.WithScope(secrets.ScopeRegistry),
+			secrets.WithUserFacing(),
+		)
+		require.Error(t, err)
+	})
+
+	t.Run("WithUserFacing and WithScope are mutually exclusive", func(t *testing.T) { //nolint:paralleltest
+		_, err := secrets.CreateProvider(secrets.EnvironmentType,
+			secrets.WithUserFacing(),
+			secrets.WithScope(secrets.ScopeRegistry),
+		)
+		require.Error(t, err)
+	})
+}