plugin

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2026 License: Apache-2.0 Imports: 50 Imported by: 0

README

Plugin System

The scafctl plugin system allows extending the provider framework with external plugins using hashicorp/go-plugin.

Architecture

  • hashicorp/go-plugin: Manages plugin lifecycle, process isolation, and crash recovery
  • gRPC: Communication protocol between scafctl and plugins
  • Protocol Buffers: Interface definitions in proto/plugin.proto

Plugin Interface

Plugins must implement the ProviderPlugin interface (8 methods):

type ProviderPlugin interface {
    // GetProviders returns all provider names exposed by this plugin.
    GetProviders(ctx context.Context) ([]string, error)

    // GetProviderDescriptor returns metadata for a specific provider.
    GetProviderDescriptor(ctx context.Context, providerName string) (*provider.Descriptor, error)

    // ConfigureProvider sends host-side configuration to a named provider once
    // after plugin load. Implementations store the config internally for
    // subsequent Execute calls.
    ConfigureProvider(ctx context.Context, providerName string, cfg ProviderConfig) error

    // ExecuteProvider executes a provider with the given input.
    ExecuteProvider(ctx context.Context, providerName string, input map[string]any) (*provider.Output, error)

    // ExecuteProviderStream executes a provider that produces incremental
    // output. The callback is invoked for each chunk; the final chunk carries
    // the Result (or Error). Return ErrStreamingNotSupported if not implemented.
    ExecuteProviderStream(ctx context.Context, providerName string, input map[string]any, cb func(StreamChunk)) error

    // DescribeWhatIf returns a human-readable description of what the provider
    // would do with the given inputs, without executing.
    DescribeWhatIf(ctx context.Context, providerName string, input map[string]any) (string, error)

    // ExtractDependencies returns resolver dependency names from the given
    // inputs. Return nil to let the host use generic extraction.
    ExtractDependencies(ctx context.Context, providerName string, inputs map[string]any) ([]string, error)

    // StopProvider requests graceful shutdown of a running provider execution.
    // providerName may be empty to stop all providers. Return nil if not implemented.
    StopProvider(ctx context.Context, providerName string) error
}

ProviderConfig

After plugin load, scafctl calls ConfigureProvider once per provider with host-side settings:

Field Type Description
Quiet bool Suppress non-essential output
NoColor bool Disable colored output
BinaryName string CLI binary name (e.g. "scafctl" or an embedder name)
HostServiceID uint32 GRPCBroker service ID for HostService callbacks
Settings map[string]json.RawMessage Extensible key-value settings

The ConfigureProvider request also carries a protocol_version field for feature detection. The current version is defined by PluginProtocolVersion.

Auth Handler Plugin Interface

Auth handler plugins implement the AuthHandlerPlugin interface (9 methods):

type AuthHandlerPlugin interface {
    GetAuthHandlers(ctx context.Context) ([]AuthHandlerInfo, error)
    ConfigureAuthHandler(ctx context.Context, handlerName string, cfg ProviderConfig) error
    Login(ctx context.Context, handlerName string, req LoginRequest, cb func(DeviceCodePrompt)) (*LoginResponse, error)
    Logout(ctx context.Context, handlerName string) error
    GetStatus(ctx context.Context, handlerName string) (*auth.Status, error)
    GetToken(ctx context.Context, handlerName string, req TokenRequest) (*TokenResponse, error)
    ListCachedTokens(ctx context.Context, handlerName string) ([]*auth.CachedTokenInfo, error)
    PurgeExpiredTokens(ctx context.Context, handlerName string) (int, error)
    StopAuthHandler(ctx context.Context, handlerName string) error
}

After plugin load, scafctl calls ConfigureAuthHandler once per handler. The request uses the same ProviderConfig fields as ConfigureProvider (quiet, no_color, binary_name, settings, host_service_id, protocol_version). The response includes optional diagnostics for structured warnings/errors.

Auth handler plugins have full access to HostService callbacks (secrets, auth identity) via the GRPCBroker, mirroring the provider plugin pattern.

RegisterAuthHandlerPlugins returns []*AuthHandlerClient. The caller should defer KillAllAuthHandlers(clients) for cleanup.

HostService Callbacks

Plugins that need host-side resources use the HostService callback service, accessed via the GRPCBroker using the service ID from ProviderConfig.HostServiceID.

Callback Purpose
GetSecret / SetSecret / DeleteSecret / ListSecrets Access the host's secret store
GetAuthIdentity Retrieve identity claims from the host's auth registry
ListAuthHandlers List available auth handlers (filtered by AllowedAuthHandlers)
GetAuthToken Retrieve a valid access token from the host's auth registry

Secret names are scoped by a plugin-specific prefix. Auth handler access is restricted to the set declared in AllowedAuthHandlers.

Streaming Execution

ExecuteProviderStream delivers incremental output (stdout/stderr chunks) to the host in real time. The callback receives StreamChunk values:

  • Stdout / Stderr -- incremental output bytes
  • Result -- final *provider.Output on success
  • Error -- terminal error string on failure

Plugins that do not support streaming should return ErrStreamingNotSupported. The host automatically falls back to unary ExecuteProvider.

Diagnostics and Exit Codes

The ExecuteProviderResponse proto carries structured Diagnostic messages alongside the output. Each diagnostic has a severity, summary, detail, and optional attribute path. An exit_code field enables plugins to propagate typed exit codes back to the host.

Protocol Version Negotiation

scafctl sends PluginProtocolVersion in the ConfigureProvider request. Plugins can inspect this to enable or disable features based on the host's capabilities. The plugin may return its own protocol version in the response for the host to check.

Creating a Plugin

  1. Import the plugin SDK package:

    import "github.com/oakwood-commons/scafctl-plugin-sdk/plugin"

  2. Implement the ProviderPlugin interface (all 8 methods)

  3. Call plugin.Serve() in your main function:

    func main() {
    plugin.Serve(&YourPlugin{})
}

  4. Build your plugin as an executable:

    go build -o my-plugin main.go

Descriptor Caching

The plugin client caches provider descriptors after the first GetProviderDescriptor call to avoid repeated gRPC round-trips. The cache is protected by a sync.RWMutex for concurrent access.

Plugin Discovery

Plugins are discovered by scanning configured plugin directories for executable files. The system:

  1. Searches for executable files in plugin directories
  2. Attempts to connect to each potential plugin
  3. Registers providers from successfully loaded plugins
  4. Skips plugins that fail to load

RegisterPluginProviders returns all created *Client instances so the caller can clean up with KillAll on shutdown.

Plugin Lifecycle

Provider Plugins
  1. Discovery: scafctl finds plugin binaries
  2. Handshake: Protocol version and magic cookie are validated
  3. GetProviders: Plugin advertises provider names
  4. GetProviderDescriptor: scafctl fetches and caches descriptors
  5. ConfigureProvider: Host sends config + protocol version + HostService ID
  6. Execution: ExecuteProvider or ExecuteProviderStream on invocation
  7. Shutdown: StopProvider for graceful cleanup, then Kill() the process
Auth Handler Plugins
  1. Discovery: scafctl finds plugin binaries
  2. Handshake: Protocol version and magic cookie are validated
  3. GetAuthHandlers: Plugin advertises handler names, flows, and capabilities
  4. ConfigureAuthHandler: Host sends config + protocol version + HostService ID
  5. Authentication: Login, Logout, GetStatus, GetToken on user request
  6. Shutdown: StopAuthHandler for graceful cleanup, then Kill() the process

Example Plugin

See examples/plugins/echo/ for a complete example plugin implementation.

Security

  • Plugins run in isolated processes
  • Communication over gRPC provides clear security boundaries
  • Plugins are validated using handshake configuration
  • Failed plugins don't crash the main process
  • Secret access is scoped by plugin-specific prefix
  • Auth handler access restricted by AllowedAuthHandlers allowlist
  • Plugin binary signatures can be verified via Sigstore/cosign (see below)

Signature Verification

Plugin binaries fetched from catalogs support Sigstore/cosign keyless signature verification. This is controlled by a SignaturePolicy:

Mode Behavior
off Digest-only verification (default)
warn Verify signature; warn on failure
enforce Verify signature; fail on missing or invalid signature
Types
  • SignaturePolicy -- policy with Mode, TrustedIssuers, and TrustedIdentities
  • SignatureMode -- string enum: off, warn, enforce
  • SignatureResult -- verification outcome with Verified, Issuer, Identity, SignedAt
  • SignatureVerifier -- interface for signature verification implementations
Build Tags

The cosign implementation is behind a cosign build tag:

  • With tag: cosign.go provides a real Sigstore verifier
  • Without tag (default): cosign_stub.go returns ErrCosignNotAvailable
Context API
  • WithSignaturePolicy(ctx, policy) -- store a policy in context
  • SignaturePolicyFromContext(ctx) -- retrieve a policy from context
  • HandleVerificationError(policy, err, logger) -- apply mode-based error handling

Testing

Use MockProviderPlugin for testing plugin implementations without running actual plugin processes.

Documentation

Index

Constants

View Source 
const AuthHandlerPluginName = sdkplugin.AuthHandlerPluginName

AuthHandlerPluginName is the name used to identify the auth handler plugin.

View Source 
const (
	// DefaultFetchCooldown is the default duration to suppress retry attempts
	// after a plugin auto-fetch failure.
	DefaultFetchCooldown = 5 * time.Minute
)
View Source 
const PluginName = sdkplugin.PluginName

PluginName is the name used to identify the provider plugin.

View Source 
const PluginProtocolVersion = sdkplugin.PluginProtocolVersion

PluginProtocolVersion is the current plugin protocol version.

Variables

View Source 
var (
	HandshakeConfig            = ptrTo(sdkplugin.HandshakeConfig())
	AuthHandlerHandshakeConfig = ptrTo(sdkplugin.AuthHandlerHandshakeConfig())
)

handshakeConfigVal and authHandlerHandshakeConfigVal cache the SDK handshake configs at init time. In the SDK these are function-based to prevent mutation; here we store them as pointer variables for backward compatibility with existing scafctl code that reads HandshakeConfig.ProtocolVersion etc. Do not mutate; read-only for backward compat.

View Source 
var (
	ErrPoolClosed       = errors.New("plugin pool is closed")
	ErrPoolFull         = errors.New("plugin pool at maximum capacity")
	ErrPluginNotAllowed = errors.New("plugin not in allowlist")
	ErrExternalDisabled = errors.New("external plugins disabled")
)

Sentinel errors for Pool operations.

View Source 
var ErrCosignNotAvailable = errors.New("cosign signature verification not available: binary compiled without 'cosign' build tag")

ErrCosignNotAvailable indicates that the binary was compiled without cosign support (missing the "cosign" build tag).

View Source 
var ErrSignatureInvalid = errors.New("cosign signature verification failed")

ErrSignatureInvalid indicates that a signature exists but failed validation (wrong issuer, identity mismatch, expired certificate, etc.).

View Source 
var ErrSignatureNotFound = errors.New("no cosign signature found for artifact")

ErrSignatureNotFound indicates that no signature was found for the artifact.

View Source 
var ErrStreamingNotSupported = sdkplugin.ErrStreamingNotSupported

ErrStreamingNotSupported is returned by ExecuteProviderStream when the plugin does not support streaming execution.

Functions

func CurrentPlatform added in v0.5.0 

func CurrentPlatform() string

CurrentPlatform returns the current OS/architecture in OCI platform format (e.g., "linux/amd64", "darwin/arm64").

func HandleVerificationError added in v0.15.0 

func HandleVerificationError(policy *SignaturePolicy, err error, lgr logr.Logger, labels ...any) error

HandleVerificationError applies the policy's mode to a signature verification error. In warn mode the error is logged and nil is returned; in enforce mode (and any unrecognised mode) the error is propagated. A nil policy is treated as enforce (fail-closed).

func KillAll added in v0.8.0 

func KillAll(clients []*Client)

KillAll terminates all plugin processes in the given client list. This is safe to call with a nil or empty slice.

func KillAllAuthHandlers added in v0.8.0 

func KillAllAuthHandlers(clients []*AuthHandlerClient)

KillAllAuthHandlers terminates all auth handler plugin processes in the given client list. This is safe to call with a nil or empty slice.

func ParsePlatform added in v0.5.0 

func ParsePlatform(platform string) (os, arch string, err error)

ParsePlatform splits an OCI platform string into OS and architecture. Returns an error if the format is invalid.

func Paths added in v0.5.0 

func Paths(results []FetchResult) []string

Paths returns just the binary paths from a slice of FetchResult.

func PlatformCacheKey added in v0.5.0 

func PlatformCacheKey(platform string) string

PlatformCacheKey returns a filesystem-safe key for the platform (e.g., "linux-amd64" from "linux/amd64").

func PluginCacheKey added in v0.15.0 

func PluginCacheKey(name string, kind solution.PluginKind) string

PluginCacheKey returns a cache-safe key for a plugin that avoids namespace collisions between different plugin kinds. Provider plugins use the bare name (e.g. "github") for backward compatibility with existing caches. Auth-handler plugins are prefixed (e.g. "auth-handler-github") so a provider named "github" and an auth-handler named "github" occupy separate cache slots.

func PoolErrorHTTPStatus added in v0.14.0 

func PoolErrorHTTPStatus(err error) int

PoolErrorHTTPStatus maps pool errors to appropriate HTTP status codes. Returns 0 if the error is not a recognized pool error.

func ProbePluginDescription added in v0.14.0 

func ProbePluginDescription(ctx context.Context, binaryPath, name string) (string, bool)

ProbePluginDescription starts a plugin binary, queries the first provider's descriptor for its description, then kills the process. Returns empty string and false on any failure.

func Serve 

func Serve(impl ProviderPlugin)

Serve is a helper function for plugin implementers to serve their provider plugins. This should be called from the plugin's main() function.

func ServeAuthHandler added in v0.5.0 

func ServeAuthHandler(impl AuthHandlerPlugin)

ServeAuthHandler is a helper function for plugin implementers to serve their auth handler plugins. This should be called from the plugin's main() function.

func ValidateVerificationURI added in v0.14.0 

func ValidateVerificationURI(uri string, trusted []string) error

ValidateVerificationURI validates a device code verification URI against security requirements and an optional trusted domain list. This is the host-side defense against malicious plugins sending phishing URLs in device code prompts.

Rules:

  • Must be a valid URL with HTTPS scheme
  • Must not target private/loopback addresses
  • Must not use non-standard ports (only 443 allowed)
  • If trusted is non-empty, host must match or be a subdomain of an entry
  • If trusted is empty, any HTTPS URL passing the above checks is allowed

func WithSignaturePolicy added in v0.15.0 

func WithSignaturePolicy(ctx context.Context, policy *SignaturePolicy) context.Context

WithSignaturePolicy stores a SignaturePolicy in the context.

Types

type AuthHandlerClient added in v0.5.0 

type AuthHandlerClient struct {
	// contains filtered or unexported fields
}

AuthHandlerClient wraps a plugin client for auth handler plugins.

func DiscoverAuthHandlers added in v0.5.0 

func DiscoverAuthHandlers(pluginDirs []string, opts ...ClientOption) ([]*AuthHandlerClient, error)

DiscoverAuthHandlers discovers auth handler plugins from the given directories.

func NewAuthHandlerClient added in v0.5.0 

func NewAuthHandlerClient(pluginPath string, opts ...ClientOption) (*AuthHandlerClient, error)

NewAuthHandlerClient creates a new auth handler plugin client.

func RegisterAuthHandlerPlugins added in v0.5.0 

func RegisterAuthHandlerPlugins(ctx context.Context, registry *auth.Registry, pluginDirs []string, cfg *ProviderConfig, clientOpts ...ClientOption) ([]*AuthHandlerClient, error)

RegisterAuthHandlerPlugins discovers auth handler plugins and registers them with the auth registry. Returns the created clients (caller should Kill() them on cleanup).

func RegisterFetchedAuthHandlerPlugins added in v0.5.0 

func RegisterFetchedAuthHandlerPlugins(ctx context.Context, registry *auth.Registry, results []FetchResult, cfg *ProviderConfig, clientOpts ...ClientOption) ([]*AuthHandlerClient, error)

RegisterFetchedAuthHandlerPlugins loads and registers fetched auth handler plugin binaries into the auth registry. Returns the created clients (caller should Kill() them on cleanup).

func (*AuthHandlerClient) ConfigureAuthHandler added in v0.8.0 

func (c *AuthHandlerClient) ConfigureAuthHandler(ctx context.Context, handlerName string, cfg ProviderConfig) error

ConfigureAuthHandler delegates to the plugin's ConfigureAuthHandler.

func (*AuthHandlerClient) GetAuthHandlers added in v0.5.0 

func (c *AuthHandlerClient) GetAuthHandlers(ctx context.Context) ([]AuthHandlerInfo, error)

GetAuthHandlers returns all auth handler names exposed by this plugin.

func (*AuthHandlerClient) GetStatus added in v0.5.0 

func (c *AuthHandlerClient) GetStatus(ctx context.Context, handlerName string) (*auth.Status, error)

GetStatus delegates to the plugin's GetStatus.

func (*AuthHandlerClient) GetToken added in v0.5.0 

func (c *AuthHandlerClient) GetToken(ctx context.Context, handlerName string, req TokenRequest) (*TokenResponse, error)

GetToken delegates to the plugin's GetToken.

func (*AuthHandlerClient) HostServiceID added in v0.8.0 

func (c *AuthHandlerClient) HostServiceID() uint32

HostServiceID returns the broker service ID of the HostService callback server. Returns 0 if no HostService was registered.

func (*AuthHandlerClient) Kill added in v0.5.0 

func (c *AuthHandlerClient) Kill()

Kill terminates the plugin process.

func (*AuthHandlerClient) Login added in v0.5.0 

func (c *AuthHandlerClient) Login(ctx context.Context, handlerName string, req LoginRequest, cb func(DeviceCodePrompt)) (*LoginResponse, error)

Login delegates to the plugin's Login.

func (*AuthHandlerClient) Logout added in v0.5.0 

func (c *AuthHandlerClient) Logout(ctx context.Context, handlerName string) error

Logout delegates to the plugin's Logout.

func (*AuthHandlerClient) Name added in v0.5.0 

func (c *AuthHandlerClient) Name() string

Name returns the plugin name.

func (*AuthHandlerClient) Path added in v0.5.0 

func (c *AuthHandlerClient) Path() string

Path returns the plugin path.

func (*AuthHandlerClient) StartupDuration added in v0.15.0 

func (c *AuthHandlerClient) StartupDuration() time.Duration

StartupDuration returns the time taken to start and handshake with the plugin process.

func (*AuthHandlerClient) StopAuthHandler added in v0.8.0 

func (c *AuthHandlerClient) StopAuthHandler(ctx context.Context, handlerName string) error

StopAuthHandler delegates to the plugin's StopAuthHandler.

type AuthHandlerGRPCClient added in v0.5.0 

type AuthHandlerGRPCClient struct {
	// contains filtered or unexported fields
}

AuthHandlerGRPCClient implements AuthHandlerPlugin by calling the gRPC service.

func (*AuthHandlerGRPCClient) ConfigureAuthHandler added in v0.8.0 

func (c *AuthHandlerGRPCClient) ConfigureAuthHandler(ctx context.Context, handlerName string, cfg ProviderConfig) error

ConfigureAuthHandler implements AuthHandlerPlugin.ConfigureAuthHandler.

func (*AuthHandlerGRPCClient) DetectAvailableFlows added in v0.15.0 

func (c *AuthHandlerGRPCClient) DetectAvailableFlows(ctx context.Context, handlerName string) ([]FlowAvailability, error)

DetectAvailableFlows implements AuthHandlerPlugin.DetectAvailableFlows.

func (*AuthHandlerGRPCClient) GetAuthHandlers added in v0.5.0 

func (c *AuthHandlerGRPCClient) GetAuthHandlers(ctx context.Context) ([]AuthHandlerInfo, error)

GetAuthHandlers implements AuthHandlerPlugin.GetAuthHandlers.

func (*AuthHandlerGRPCClient) GetStatus added in v0.5.0 

func (c *AuthHandlerGRPCClient) GetStatus(ctx context.Context, handlerName string) (*auth.Status, error)

GetStatus implements AuthHandlerPlugin.GetStatus.

func (*AuthHandlerGRPCClient) GetToken added in v0.5.0 

func (c *AuthHandlerGRPCClient) GetToken(ctx context.Context, handlerName string, req TokenRequest) (*TokenResponse, error)

GetToken implements AuthHandlerPlugin.GetToken.

func (*AuthHandlerGRPCClient) ListCachedTokens added in v0.5.0 

func (c *AuthHandlerGRPCClient) ListCachedTokens(ctx context.Context, handlerName string) ([]*auth.CachedTokenInfo, error)

ListCachedTokens implements AuthHandlerPlugin.ListCachedTokens.

func (*AuthHandlerGRPCClient) Login added in v0.5.0 

func (c *AuthHandlerGRPCClient) Login(ctx context.Context, handlerName string, req LoginRequest, deviceCodeCb func(DeviceCodePrompt)) (*LoginResponse, error)

Login implements AuthHandlerPlugin.Login with streaming device code support.

func (*AuthHandlerGRPCClient) Logout added in v0.5.0 

func (c *AuthHandlerGRPCClient) Logout(ctx context.Context, handlerName string) error

Logout implements AuthHandlerPlugin.Logout.

func (*AuthHandlerGRPCClient) PurgeExpiredTokens added in v0.5.0 

func (c *AuthHandlerGRPCClient) PurgeExpiredTokens(ctx context.Context, handlerName string) (int, error)

PurgeExpiredTokens implements AuthHandlerPlugin.PurgeExpiredTokens.

func (*AuthHandlerGRPCClient) StopAuthHandler added in v0.8.0 

func (c *AuthHandlerGRPCClient) StopAuthHandler(ctx context.Context, handlerName string) error

StopAuthHandler implements AuthHandlerPlugin.StopAuthHandler.

type AuthHandlerGRPCPlugin added in v0.5.0 

type AuthHandlerGRPCPlugin struct {
	plugin.Plugin
	Impl AuthHandlerPlugin
	// HostDeps holds host-side dependencies for the HostService callback server.
	// Set by the host before starting the plugin. Nil on the plugin side.
	HostDeps *HostServiceDeps
}

AuthHandlerGRPCPlugin implements plugin.GRPCPlugin from hashicorp/go-plugin for auth handler plugins.

func (*AuthHandlerGRPCPlugin) GRPCClient added in v0.5.0 

func (p *AuthHandlerGRPCPlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (any, error)

GRPCClient returns the auth handler gRPC client. If HostDeps is non-nil, a HostService gRPC server is started via the broker.

func (*AuthHandlerGRPCPlugin) GRPCServer added in v0.5.0 

func (p *AuthHandlerGRPCPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

GRPCServer registers the auth handler gRPC server.

type AuthHandlerGRPCServer added in v0.5.0 

type AuthHandlerGRPCServer struct {
	proto.UnimplementedAuthHandlerServiceServer
	Impl AuthHandlerPlugin
	// contains filtered or unexported fields
}

AuthHandlerGRPCServer implements the gRPC server for auth handler plugins.

func (*AuthHandlerGRPCServer) ConfigureAuthHandler added in v0.8.0 

func (s *AuthHandlerGRPCServer) ConfigureAuthHandler(ctx context.Context, req *proto.ConfigureAuthHandlerRequest) (*proto.ConfigureAuthHandlerResponse, error)

ConfigureAuthHandler implements the ConfigureAuthHandler RPC.

func (*AuthHandlerGRPCServer) DetectAvailableFlows added in v0.15.0 

func (s *AuthHandlerGRPCServer) DetectAvailableFlows(ctx context.Context, req *proto.DetectAvailableFlowsRequest) (*proto.DetectAvailableFlowsResponse, error)

DetectAvailableFlows implements the DetectAvailableFlows RPC.

func (*AuthHandlerGRPCServer) GetAuthHandlers added in v0.5.0 

func (s *AuthHandlerGRPCServer) GetAuthHandlers(ctx context.Context, _ *proto.GetAuthHandlersRequest) (*proto.GetAuthHandlersResponse, error)

GetAuthHandlers implements the GetAuthHandlers RPC.

func (*AuthHandlerGRPCServer) GetStatus added in v0.5.0 

func (s *AuthHandlerGRPCServer) GetStatus(ctx context.Context, req *proto.GetStatusRequest) (*proto.GetStatusResponse, error)

GetStatus implements the GetStatus RPC.

func (*AuthHandlerGRPCServer) GetToken added in v0.5.0 

func (s *AuthHandlerGRPCServer) GetToken(ctx context.Context, req *proto.GetTokenRequest) (*proto.GetTokenResponse, error)

GetToken implements the GetToken RPC.

func (*AuthHandlerGRPCServer) ListCachedTokens added in v0.5.0 

func (s *AuthHandlerGRPCServer) ListCachedTokens(ctx context.Context, req *proto.ListCachedTokensRequest) (*proto.ListCachedTokensResponse, error)

ListCachedTokens implements the ListCachedTokens RPC.

func (*AuthHandlerGRPCServer) Login added in v0.5.0 

func (s *AuthHandlerGRPCServer) Login(req *proto.LoginRequest, stream grpc.ServerStreamingServer[proto.LoginStreamMessage]) error

Login implements the Login RPC with server-side streaming.

func (*AuthHandlerGRPCServer) Logout added in v0.5.0 

func (s *AuthHandlerGRPCServer) Logout(ctx context.Context, req *proto.LogoutRequest) (*proto.LogoutResponse, error)

Logout implements the Logout RPC.

func (*AuthHandlerGRPCServer) PurgeExpiredTokens added in v0.5.0 

func (s *AuthHandlerGRPCServer) PurgeExpiredTokens(ctx context.Context, req *proto.PurgeExpiredTokensRequest) (*proto.PurgeExpiredTokensResponse, error)

PurgeExpiredTokens implements the PurgeExpiredTokens RPC.

func (*AuthHandlerGRPCServer) StopAuthHandler added in v0.8.0 

func (s *AuthHandlerGRPCServer) StopAuthHandler(ctx context.Context, req *proto.StopAuthHandlerRequest) (*proto.StopAuthHandlerResponse, error)

StopAuthHandler implements the StopAuthHandler RPC.

type AuthHandlerInfo added in v0.5.0 

type AuthHandlerInfo = sdkplugin.AuthHandlerInfo

AuthHandlerInfo holds static metadata about an auth handler exposed by a plugin.

type AuthHandlerPlugin added in v0.5.0 

type AuthHandlerPlugin = sdkplugin.AuthHandlerPlugin

AuthHandlerPlugin is the interface that auth handler plugins must implement.

type AuthHandlerWrapper added in v0.5.0 

type AuthHandlerWrapper struct {
	// contains filtered or unexported fields
}

AuthHandlerWrapper wraps a plugin auth handler to implement the auth.Handler (and optionally auth.TokenLister / auth.TokenPurger) interfaces.

func NewAuthHandlerWrapper added in v0.5.0 

func NewAuthHandlerWrapper(client *AuthHandlerClient, info AuthHandlerInfo) *AuthHandlerWrapper

NewAuthHandlerWrapper creates a new wrapper for a plugin auth handler.

func (*AuthHandlerWrapper) Capabilities added in v0.5.0 

func (w *AuthHandlerWrapper) Capabilities() []auth.Capability

Capabilities implements auth.Handler.

func (*AuthHandlerWrapper) Client added in v0.5.0 

func (w *AuthHandlerWrapper) Client() *AuthHandlerClient

Client returns the underlying plugin client.

func (*AuthHandlerWrapper) DetectAvailableFlows added in v0.15.0 

func (w *AuthHandlerWrapper) DetectAvailableFlows(ctx context.Context) ([]auth.FlowAvailability, error)

DetectAvailableFlows implements auth.FlowDetector.

func (*AuthHandlerWrapper) DisplayName added in v0.5.0 

func (w *AuthHandlerWrapper) DisplayName() string

DisplayName implements auth.Handler.

func (*AuthHandlerWrapper) GetToken added in v0.5.0 

func (w *AuthHandlerWrapper) GetToken(ctx context.Context, opts auth.TokenOptions) (*auth.Token, error)

GetToken implements auth.Handler.

func (*AuthHandlerWrapper) InjectAuth added in v0.5.0 

func (w *AuthHandlerWrapper) InjectAuth(ctx context.Context, req *http.Request, opts auth.TokenOptions) error

InjectAuth implements auth.Handler. Since http.Request cannot be serialized over gRPC, this method decomposes into GetToken (over gRPC) + local header injection.

func (*AuthHandlerWrapper) ListCachedTokens added in v0.5.0 

func (w *AuthHandlerWrapper) ListCachedTokens(ctx context.Context) ([]*auth.CachedTokenInfo, error)

ListCachedTokens implements auth.TokenLister.

func (*AuthHandlerWrapper) Login added in v0.5.0 

func (w *AuthHandlerWrapper) Login(ctx context.Context, opts auth.LoginOptions) (*auth.Result, error)

Login implements auth.Handler.

func (*AuthHandlerWrapper) Logout added in v0.5.0 

func (w *AuthHandlerWrapper) Logout(ctx context.Context) error

Logout implements auth.Handler.

func (*AuthHandlerWrapper) Name added in v0.5.0 

func (w *AuthHandlerWrapper) Name() string

Name implements auth.Handler.

func (*AuthHandlerWrapper) PurgeExpiredTokens added in v0.5.0 

func (w *AuthHandlerWrapper) PurgeExpiredTokens(ctx context.Context) (int, error)

PurgeExpiredTokens implements auth.TokenPurger.

func (*AuthHandlerWrapper) SetStartupLatency added in v0.15.0 

func (w *AuthHandlerWrapper) SetStartupLatency(d time.Duration)

SetStartupLatency records the plugin process startup latency.

func (*AuthHandlerWrapper) SetTrustedDomains added in v0.14.0 

func (w *AuthHandlerWrapper) SetTrustedDomains(domains []string)

SetTrustedDomains sets the trusted verification URI domains for device code URL validation. When non-empty, device code prompts from this handler are validated against these domains (exact match or subdomain).

func (*AuthHandlerWrapper) StartupLatency added in v0.15.0 

func (w *AuthHandlerWrapper) StartupLatency() time.Duration

StartupLatency returns the plugin process startup latency.

func (*AuthHandlerWrapper) Status added in v0.5.0 

func (w *AuthHandlerWrapper) Status(ctx context.Context) (*auth.Status, error)

Status implements auth.Handler.

func (*AuthHandlerWrapper) SupportedFlows added in v0.5.0 

func (w *AuthHandlerWrapper) SupportedFlows() []auth.Flow

SupportedFlows implements auth.Handler.

type Cache added in v0.5.0 

type Cache struct {
	// contains filtered or unexported fields
}

PluginCache manages a local content-addressed cache of plugin binaries.

Cache layout: 

<cacheDir>/<name>/<version>/<os>-<arch>/<name>[.exe]

On Windows platforms, the binary has a ".exe" extension.

Example: 

~/.cache/scafctl/plugins/aws-provider/1.5.3/darwin-arm64/aws-provider
~/.cache/scafctl/plugins/aws-provider/1.5.3/windows-amd64/aws-provider.exe

func NewCache added in v0.5.0 

func NewCache(cacheDir string) *Cache

NewCache creates a new Cache. If cacheDir is empty, the default XDG cache directory (paths.PluginCacheDir()) is used.

func (*Cache) Digest added in v0.5.0 

func (c *Cache) Digest(name, version, platform string) (string, error)

Digest computes the sha256 digest of a cached plugin binary. Returns the digest in "sha256:<hex>" format.

func (*Cache) Dir added in v0.5.0 

func (c *Cache) Dir() string

Dir returns the root cache directory.

func (*Cache) Get added in v0.5.0 

func (c *Cache) Get(name, version, platform, expectedDigest string) (string, bool)

Get retrieves the path to a cached plugin binary. Returns the path and true if the binary exists and (optionally) matches the expected digest. If expectedDigest is empty, no digest verification is performed.

func (*Cache) GetLatestBinary added in v0.14.0 

func (c *Cache) GetLatestBinary(name string) (string, string, bool)

GetLatestBinary returns the path to the newest cached binary for the given name on the current platform. Returns the path, version, and true if found.

func (*Cache) GetLatestCached added in v0.14.0 

func (c *Cache) GetLatestCached(name, platform string) (string, string, bool)

GetLatestCached returns the path to the newest cached binary for the given name and platform, regardless of version. Returns empty string and false if nothing is cached. This is used as a fallback when catalog version resolution fails (e.g., when running offline).

func (*Cache) List added in v0.5.0 

func (c *Cache) List() ([]CachedPlugin, error)

List returns all cached (name, version, platform) triples.

func (*Cache) ListCurrentPlatform added in v0.14.0 

func (c *Cache) ListCurrentPlatform() ([]CachedPlugin, error)

ListCurrentPlatform returns cached plugins that match the current platform. When multiple versions of the same plugin are cached, only the latest (by semver) is included.

func (*Cache) Put added in v0.5.0 

func (c *Cache) Put(name, version, platform string, data []byte) (string, error)

Put writes a plugin binary to the cache. It creates the directory structure, writes the data, sets executable permissions, and returns the path to the cached binary.

func (*Cache) Remove added in v0.5.0 

func (c *Cache) Remove(name, version, platform string) error

Remove deletes a cached plugin binary.

type CachedPlugin added in v0.5.0 

type CachedPlugin struct {
	Name     string `json:"name" yaml:"name" doc:"Plugin name"`
	Version  string `json:"version" yaml:"version" doc:"Plugin version"`
	Platform string `json:"platform" yaml:"platform" doc:"Target platform (os/arch)"`
	Path     string `json:"path" yaml:"path" doc:"Absolute path to cached binary"`
	Size     int64  `json:"size" yaml:"size" doc:"Binary size in bytes"`
}

CachedPlugin describes a cached plugin binary.

type CachedPluginInfo added in v0.14.0 

type CachedPluginInfo struct {
	Name        string `json:"name" yaml:"name" doc:"Plugin name"`
	Version     string `json:"version" yaml:"version" doc:"Plugin version"`
	Path        string `json:"path" yaml:"path" doc:"Absolute path to cached binary"`
	Description string `json:"description,omitempty" yaml:"description,omitempty" doc:"Human-readable summary of the provider"`
}

CachedPluginInfo describes a cached plugin with metadata obtained by starting the plugin binary and querying its providers.

func DescribeCachedPlugins added in v0.14.0 

func DescribeCachedPlugins(ctx context.Context, cached []CachedPlugin, skip map[string]bool) []CachedPluginInfo

DescribeCachedPlugins starts each cached plugin binary, queries its provider descriptors to obtain descriptions, then shuts it down. Plugins that fail to start or respond are excluded from the result (they may be non-provider artifacts such as auth-handler binaries). The skip set contains provider names that should be excluded from the result (e.g., already-listed builtin/official names).

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client wraps a plugin client and manages its lifecycle

func Discover 

func Discover(pluginDirs []string, opts ...ClientOption) ([]*Client, error)

Discover discovers plugins from the given directories

func NewClient 

func NewClient(pluginPath string, opts ...ClientOption) (*Client, error)

NewClient creates a new plugin client.

func RegisterCachedPlugin added in v0.14.0 

func RegisterCachedPlugin(ctx context.Context, name string, registry *provider.Registry, cfg *ProviderConfig, cacheDir string, clientOpts ...ClientOption) ([]*Client, error)

RegisterCachedPlugin looks up a provider plugin by name in the local cache, starts it, and registers its providers into the given registry. Returns the created clients (caller must Kill them on cleanup) or an error if the plugin is not cached.

func RegisterFetchedPlugins added in v0.5.0 

func RegisterFetchedPlugins(ctx context.Context, registry *provider.Registry, results []FetchResult, cfg *ProviderConfig, clientOpts ...ClientOption) ([]*Client, error)

RegisterFetchedPlugins loads and registers fetched plugin binaries into the provider registry. Unlike RegisterPluginProviders (which discovers plugins from directories), this loads specific binaries by path. Returns the created clients (caller should Kill() them on cleanup).

func RegisterPluginProviders 

func RegisterPluginProviders(ctx context.Context, registry *provider.Registry, pluginDirs []string, cfg *ProviderConfig, clientOpts ...ClientOption) ([]*Client, error)

RegisterPluginProviders discovers plugins and registers them with the provider registry. After registration, each wrapper is configured with the provided ProviderConfig. If cfg is nil, configuration is skipped (providers will use defaults). Returns the created clients; the caller should defer calling KillAll(clients) to clean up plugin processes on exit.

func (*Client) ConfigureProvider added in v0.8.0 

func (c *Client) ConfigureProvider(ctx context.Context, providerName string, cfg ProviderConfig) error

ConfigureProvider sends host-side configuration to a named provider.

func (*Client) DescribeWhatIf added in v0.6.0 

func (c *Client) DescribeWhatIf(ctx context.Context, providerName string, input map[string]any) (string, error)

DescribeWhatIf returns a human-readable description of what the provider would do

func (*Client) ExecuteProvider 

func (c *Client) ExecuteProvider(ctx context.Context, providerName string, input map[string]any) (*provider.Output, error)

ExecuteProvider executes a provider with the given input

func (*Client) ExecuteProviderStream added in v0.8.0 

func (c *Client) ExecuteProviderStream(ctx context.Context, providerName string, input map[string]any, cb func(StreamChunk)) error

ExecuteProviderStream executes a provider with streaming output.

func (*Client) ExtractDependencies added in v0.8.0 

func (c *Client) ExtractDependencies(ctx context.Context, providerName string, inputs map[string]any) ([]string, error)

ExtractDependencies returns resolver dependency names from the provider's inputs.

func (*Client) GetProviderDescriptor 

func (c *Client) GetProviderDescriptor(ctx context.Context, providerName string) (*provider.Descriptor, error)

GetProviderDescriptor returns metadata for a specific provider. The result is cached for the lifetime of the client.

Note: concurrent callers for the same uncached provider may both issue an RPC (classic check-then-act). This is benign because descriptors are immutable — the second writer simply overwrites with an identical value.

func (*Client) GetProviders 

func (c *Client) GetProviders(ctx context.Context) ([]string, error)

GetProviders returns all provider names exposed by this plugin

func (*Client) Kill 

func (c *Client) Kill()

Kill terminates the plugin process

func (*Client) Name 

func (c *Client) Name() string

Name returns the plugin name

func (*Client) Path 

func (c *Client) Path() string

Path returns the plugin path

type ClientOption added in v0.8.0 

type ClientOption func(*clientOptions)

ClientOption configures plugin client creation.

func AuthClientOptsFromContext added in v0.15.0 

func AuthClientOptsFromContext(ctx context.Context) []ClientOption

AuthClientOptsFromContext extracts the auth registry from ctx and returns ClientOption(s) that wire host-side auth deps into plugin clients. Returns nil when no auth registry is available in the context.

func WithDebugLogging added in v0.14.0 

func WithDebugLogging() ClientOption

WithDebugLogging enables plugin lifecycle debug traces (plugin started, RPC address, protocol negotiation) in the hclog output. Pass this option when --debug or --log-level debug is active so plugin internals are visible. Without it a null logger is used and no plugin noise appears.

func WithHostDeps added in v0.8.0 

func WithHostDeps(deps *HostServiceDeps) ClientOption

WithHostDeps provides host-side dependencies (secrets, auth) that are exposed to the plugin via the HostService gRPC callback server.

func WithSanitizedEnv added in v0.14.0 

func WithSanitizedEnv() ClientOption

WithSanitizedEnv restricts the environment variables passed to the plugin process. Only safe variables (PATH, HOME, TMPDIR, etc.) are inherited. Use this in API server contexts to prevent leaking secrets to plugins.

func WithStartTimeout added in v0.14.0 

func WithStartTimeout(d time.Duration) ClientOption

WithStartTimeout bounds the plugin startup/handshake phase. If the plugin binary does not complete the gRPC handshake within this duration, the connection attempt fails and the process is killed.

type DeviceCodePrompt added in v0.5.0 

type DeviceCodePrompt = sdkplugin.DeviceCodePrompt

DeviceCodePrompt is sent over streaming Login to relay device-code info to the host.

type FetchCooldown added in v0.14.0 

type FetchCooldown struct {
	// contains filtered or unexported fields
}

FetchCooldown manages cooldown state for failed plugin auto-fetch attempts. It uses file-based markers in the plugin cache directory to persist cooldown state across CLI invocations.

func NewFetchCooldown added in v0.14.0 

func NewFetchCooldown(cacheDir string, cooldown time.Duration) *FetchCooldown

NewFetchCooldown creates a FetchCooldown with the given cooldown duration. If cacheDir is empty, the default plugin cache directory is used. If cooldown is zero, DefaultFetchCooldown is used.

func (*FetchCooldown) Clear added in v0.14.0 

func (fc *FetchCooldown) Clear(name string) error

Clear removes the cooldown marker for the named plugin. This is called on explicit install (e.g., `scafctl plugin install`) or with --force-fetch.

func (*FetchCooldown) OnCooldown added in v0.14.0 

func (fc *FetchCooldown) OnCooldown(name string) bool

OnCooldown reports whether a fetch attempt for the named plugin should be suppressed due to a recent failure. Returns true if a cooldown marker exists and has not expired.

func (*FetchCooldown) RecordFailure added in v0.14.0 

func (fc *FetchCooldown) RecordFailure(name string) error

RecordFailure writes a cooldown marker for the named plugin, indicating that a fetch attempt failed at the current time.

type FetchResult added in v0.5.0 

type FetchResult struct {
	// Name is the plugin name.
	Name string

	// Kind is the plugin kind.
	Kind solution.PluginKind

	// Version is the resolved version.
	Version string

	// Path is the local filesystem path to the binary.
	Path string

	// Digest is the content digest.
	Digest string

	// FromCache indicates whether the binary was served from cache.
	FromCache bool

	// Signature holds signature verification metadata when verification
	// was performed. Nil when signatures are disabled or the binary was cached.
	//
	// TODO: surface Signature in CLI output/audit log so users can inspect
	// verification results after a fetch.
	Signature *SignatureResult

	// Catalog is the catalog name the plugin was fetched from (empty if cached).
	Catalog string
}

FetchResult contains the result of fetching a single plugin.

type Fetcher added in v0.5.0 

type Fetcher struct {
	// contains filtered or unexported fields
}

Fetcher resolves, downloads, caches, and loads plugin binaries at runtime. It checks a local cache first, then falls back to fetching from catalogs.

func NewFetcher added in v0.5.0 

func NewFetcher(cfg FetcherConfig) *Fetcher

NewFetcher creates a new Fetcher.

func (*Fetcher) FetchPlugins added in v0.5.0 

func (f *Fetcher) FetchPlugins(ctx context.Context, plugins []solution.PluginDependency, lockPlugins []bundler.LockPlugin) ([]FetchResult, error)

FetchPlugins resolves and downloads plugin binaries for all declared dependencies. It checks the local cache first, uses lock file entries for pinned versions when available, and falls back to catalog resolution.

When a plugin is resolved without a lock file entry, a warning is logged about potential reproducibility issues.

Returns a list of FetchResult with local binary paths, suitable for passing to RegisterPluginProviders.

type FetcherConfig added in v0.5.0 

type FetcherConfig struct {
	// Catalog is the catalog (or chain) to fetch plugins from.
	Catalog catalog.Catalog

	// Cache is the local plugin binary cache. If nil, a default cache is created.
	Cache *Cache

	// Platform overrides the target platform. If empty, CurrentPlatform() is used.
	Platform string

	// NoCache bypasses the local cache, forcing a fresh fetch from the catalog.
	// Cached binaries are still written after fetch (the cache is populated but not read).
	NoCache bool

	// BinaryName is the CLI binary name used in user-facing messages (e.g.,
	// "Run 'mycli build solution' to pin..."). Defaults to "scafctl" when empty.
	BinaryName string

	// AllowedCatalogs restricts which catalog names plugins may be fetched
	// from. If empty, all catalogs are allowed.
	AllowedCatalogs []string

	// SignaturePolicy configures Sigstore/cosign signature verification.
	// When nil or Mode is "off", no signature verification is performed.
	SignaturePolicy *SignaturePolicy

	// SignatureVerifier is the implementation used for OCI signature checks.
	// When nil, NewSignatureVerifier() is used (cosign if built with the
	// "cosign" tag, otherwise a no-op stub).
	SignatureVerifier SignatureVerifier

	// Logger for logging operations.
	Logger logr.Logger
}

FetcherConfig configures a Fetcher.

type FlowAvailability added in v0.15.0 

type FlowAvailability = sdkplugin.FlowAvailability

FlowAvailability reports whether a specific auth flow is available based on environment credentials or configuration.

type GRPCClient 

type GRPCClient struct {
	// contains filtered or unexported fields
}

GRPCClient implements the gRPC client for the plugin

func (*GRPCClient) ConfigureProvider added in v0.8.0 

func (c *GRPCClient) ConfigureProvider(ctx context.Context, providerName string, cfg ProviderConfig) error

ConfigureProvider implements ProviderPlugin.ConfigureProvider

func (*GRPCClient) DescribeWhatIf added in v0.6.0 

func (c *GRPCClient) DescribeWhatIf(ctx context.Context, providerName string, input map[string]any) (string, error)

DescribeWhatIf implements ProviderPlugin.DescribeWhatIf

func (*GRPCClient) ExecuteProvider 

func (c *GRPCClient) ExecuteProvider(ctx context.Context, providerName string, input map[string]any) (*provider.Output, error)

ExecuteProvider implements ProviderPlugin.ExecuteProvider

func (*GRPCClient) ExecuteProviderStream added in v0.8.0 

func (c *GRPCClient) ExecuteProviderStream(ctx context.Context, providerName string, input map[string]any, cb func(StreamChunk)) error

ExecuteProviderStream implements ProviderPlugin.ExecuteProviderStream

func (*GRPCClient) ExtractDependencies added in v0.8.0 

func (c *GRPCClient) ExtractDependencies(ctx context.Context, providerName string, inputs map[string]any) ([]string, error)

ExtractDependencies implements ProviderPlugin.ExtractDependencies

func (*GRPCClient) GetProviderDescriptor 

func (c *GRPCClient) GetProviderDescriptor(ctx context.Context, providerName string) (*provider.Descriptor, error)

GetProviderDescriptor implements ProviderPlugin.GetProviderDescriptor

func (*GRPCClient) GetProviders 

func (c *GRPCClient) GetProviders(ctx context.Context) ([]string, error)

GetProviders implements ProviderPlugin.GetProviders

func (*GRPCClient) HostServiceID added in v0.8.0 

func (c *GRPCClient) HostServiceID() uint32

HostServiceID returns the broker service ID of the HostService callback server. Returns 0 if no HostService was registered.

func (*GRPCClient) StopProvider added in v0.8.0 

func (c *GRPCClient) StopProvider(ctx context.Context, providerName string) error

StopProvider implements ProviderPlugin.StopProvider

type GRPCPlugin 

type GRPCPlugin struct {
	plugin.Plugin
	Impl ProviderPlugin
	// HostDeps holds host-side dependencies for the HostService callback server.
	// Set by the host before starting the plugin. Nil on the plugin side.
	HostDeps *HostServiceDeps
}

GRPCPlugin implements plugin.GRPCPlugin from hashicorp/go-plugin

func (*GRPCPlugin) GRPCClient 

func (p *GRPCPlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (any, error)

GRPCClient returns the gRPC client (host side). If HostDeps is non-nil, a HostService gRPC server is started via the broker and the returned GRPCClient holds the broker service ID for later ConfigureProvider calls.

func (*GRPCPlugin) GRPCServer 

func (p *GRPCPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

GRPCServer registers the gRPC server (plugin side). When HostDeps is set, a HostService callback server is started on the host via the broker and its service ID is stored so that ConfigureProvider can relay it.

type GRPCServer 

type GRPCServer struct {
	proto.UnimplementedPluginServiceServer
	Impl ProviderPlugin
	// contains filtered or unexported fields
}

GRPCServer implements the gRPC server for the plugin

func (*GRPCServer) ConfigureProvider added in v0.8.0 

func (s *GRPCServer) ConfigureProvider(ctx context.Context, req *proto.ConfigureProviderRequest) (*proto.ConfigureProviderResponse, error)

ConfigureProvider implements the ConfigureProvider RPC

func (*GRPCServer) DescribeWhatIf added in v0.6.0 

func (s *GRPCServer) DescribeWhatIf(ctx context.Context, req *proto.DescribeWhatIfRequest) (*proto.DescribeWhatIfResponse, error)

DescribeWhatIf implements the DescribeWhatIf RPC

func (*GRPCServer) ExecuteProvider 

func (s *GRPCServer) ExecuteProvider(ctx context.Context, req *proto.ExecuteProviderRequest) (*proto.ExecuteProviderResponse, error)

ExecuteProvider implements the ExecuteProvider RPC

func (*GRPCServer) ExecuteProviderStream added in v0.8.0 

func (s *GRPCServer) ExecuteProviderStream(req *proto.ExecuteProviderRequest, stream proto.PluginService_ExecuteProviderStreamServer) error

ExecuteProviderStream implements the streaming ExecuteProvider RPC

func (*GRPCServer) ExtractDependencies added in v0.8.0 

func (s *GRPCServer) ExtractDependencies(ctx context.Context, req *proto.ExtractDependenciesRequest) (*proto.ExtractDependenciesResponse, error)

ExtractDependencies implements the ExtractDependencies RPC

func (*GRPCServer) GetProviderDescriptor 

func (s *GRPCServer) GetProviderDescriptor(ctx context.Context, req *proto.GetProviderDescriptorRequest) (*proto.GetProviderDescriptorResponse, error)

GetProviderDescriptor implements the GetProviderDescriptor RPC

func (*GRPCServer) GetProviders 

func (s *GRPCServer) GetProviders(ctx context.Context, _ *proto.GetProvidersRequest) (*proto.GetProvidersResponse, error)

GetProviders implements the GetProviders RPC

func (*GRPCServer) StopProvider added in v0.8.0 

func (s *GRPCServer) StopProvider(ctx context.Context, req *proto.StopProviderRequest) (*proto.StopProviderResponse, error)

StopProvider implements the StopProvider RPC

type HandshakeConfigData 

type HandshakeConfigData = sdkplugin.HandshakeConfigData

HandshakeConfigData contains the handshake configuration.

type HostServiceClient added in v0.8.0 

type HostServiceClient struct {
	// contains filtered or unexported fields
}

HostServiceClient wraps the HostService gRPC client (used by plugins). Plugin code uses this to call back into the host process.

func NewHostServiceClient added in v0.8.0 

func NewHostServiceClient(conn *grpc.ClientConn) *HostServiceClient

NewHostServiceClient creates a HostServiceClient from a gRPC connection.

func (*HostServiceClient) DeleteSecret added in v0.8.0 

func (c *HostServiceClient) DeleteSecret(ctx context.Context, name string) error

DeleteSecret removes a secret from the host's secret store.

func (*HostServiceClient) GetAuthGroups added in v0.14.0 

func (c *HostServiceClient) GetAuthGroups(ctx context.Context, handler string) ([]string, error)

GetAuthGroups retrieves group memberships for the authenticated user from the host's auth registry.

func (*HostServiceClient) GetAuthIdentity added in v0.8.0 

func (c *HostServiceClient) GetAuthIdentity(ctx context.Context, handler, scope string) (*proto.Claims, error)

GetAuthIdentity retrieves identity claims from the host's auth registry.

func (*HostServiceClient) GetAuthToken added in v0.8.0 

func (c *HostServiceClient) GetAuthToken(ctx context.Context, handler, scope string, minValidFor int64, forceRefresh bool) (*proto.GetAuthTokenResponse, error)

GetAuthToken retrieves a valid access token from the host's auth registry.

func (*HostServiceClient) GetSecret added in v0.8.0 

func (c *HostServiceClient) GetSecret(ctx context.Context, name string) (string, bool, error)

GetSecret retrieves a secret from the host's secret store.

func (*HostServiceClient) ListAuthHandlers added in v0.8.0 

func (c *HostServiceClient) ListAuthHandlers(ctx context.Context) (handlers []string, defaultHandler string, err error)

ListAuthHandlers lists available auth handlers on the host.

func (*HostServiceClient) ListSecrets added in v0.8.0 

func (c *HostServiceClient) ListSecrets(ctx context.Context, pattern string) ([]string, error)

ListSecrets lists secret names from the host's secret store.

func (*HostServiceClient) SetSecret added in v0.8.0 

func (c *HostServiceClient) SetSecret(ctx context.Context, name, value string) error

SetSecret stores a secret in the host's secret store.

type HostServiceDeps added in v0.8.0 

type HostServiceDeps struct {
	// SecretStore provides access to the host's secret store (may be nil).
	SecretStore secrets.Store `json:"-" yaml:"-" doc:"Host secret store (not serialized)."`
	// AllowedSecretPrefix restricts secret access to names starting with this prefix.
	// If empty, all secrets are accessible (for backward compatibility).
	AllowedSecretPrefix string `json:"allowedSecretPrefix,omitempty" yaml:"allowedSecretPrefix,omitempty" doc:"Prefix restriction for secret access."`
	// AuthIdentityFunc returns claims for a named auth handler and scope.
	// handler may be empty for the default handler. May be nil if auth is unavailable.
	AuthIdentityFunc func(ctx context.Context, handler, scope string) (*proto.Claims, error) `json:"-" yaml:"-" doc:"Auth identity callback (not serialized)."`
	// AllowedAuthHandlers restricts which auth handler names a plugin may request.
	// If nil or empty, all handlers are allowed (for backward compatibility).
	AllowedAuthHandlers []string `json:"allowedAuthHandlers,omitempty" yaml:"allowedAuthHandlers,omitempty" doc:"Allowed auth handler names."`
	// AuthHandlersFunc returns available auth handler names and the default handler.
	// May be nil if auth is unavailable.
	AuthHandlersFunc func(ctx context.Context) (handlers []string, defaultHandler string, err error) `json:"-" yaml:"-" doc:"Auth handlers callback (not serialized)."`
	// AuthTokenFunc retrieves a valid access token from the host's auth registry.
	// Plugins call this for authenticated HTTP requests and token refresh on 401.
	// May be nil if auth is unavailable.
	AuthTokenFunc func(ctx context.Context, handler, scope string, minValidFor int64, forceRefresh bool) (*proto.GetAuthTokenResponse, error) `json:"-" yaml:"-" doc:"Auth token callback (not serialized)."`
	// AuthGroupsFunc retrieves group memberships for the authenticated user.
	// Only handlers that implement group queries (e.g. Entra) will return results.
	// May be nil if group queries are unavailable.
	// TODO: Wire this callback in production code (e.g. via RootOptions or plugin SDK)
	// once an auth handler with group query support is available.
	AuthGroupsFunc func(ctx context.Context, handler string) ([]string, error) `json:"-" yaml:"-" doc:"Auth groups callback (not serialized)."`
}

HostServiceDeps holds the host-side dependencies that the HostService exposes to plugins via gRPC callbacks. This is an internal dependency-injection struct passed by value into HostServiceServer; fields are not serialized.

func HostDepsFromAuthRegistry added in v0.15.0 

func HostDepsFromAuthRegistry(authReg *auth.Registry) *HostServiceDeps

HostDepsFromAuthRegistry builds a HostServiceDeps that delegates auth callbacks to the given auth.Registry. Returns nil when the registry is nil, so callers can safely pass the result to WithHostDeps without a nil check.

type HostServiceServer added in v0.8.0 

type HostServiceServer struct {
	proto.UnimplementedHostServiceServer
	Deps HostServiceDeps
}

HostServiceServer implements the HostService gRPC server (runs on the host). Plugins call these RPCs back into the host process via the go-plugin GRPCBroker.

func (*HostServiceServer) DeleteSecret added in v0.8.0 

func (h *HostServiceServer) DeleteSecret(ctx context.Context, req *proto.DeleteSecretRequest) (*proto.DeleteSecretResponse, error)

DeleteSecret implements HostService.DeleteSecret

func (*HostServiceServer) GetAuthGroups added in v0.14.0 

func (h *HostServiceServer) GetAuthGroups(ctx context.Context, req *proto.GetAuthGroupsRequest) (*proto.GetAuthGroupsResponse, error)

GetAuthGroups implements HostService.GetAuthGroups

func (*HostServiceServer) GetAuthIdentity added in v0.8.0 

func (h *HostServiceServer) GetAuthIdentity(ctx context.Context, req *proto.GetAuthIdentityRequest) (*proto.GetAuthIdentityResponse, error)

GetAuthIdentity implements HostService.GetAuthIdentity

func (*HostServiceServer) GetAuthToken added in v0.8.0 

func (h *HostServiceServer) GetAuthToken(ctx context.Context, req *proto.GetAuthTokenRequest) (*proto.GetAuthTokenResponse, error)

GetAuthToken implements HostService.GetAuthToken

func (*HostServiceServer) GetSecret added in v0.8.0 

func (h *HostServiceServer) GetSecret(ctx context.Context, req *proto.GetSecretRequest) (*proto.GetSecretResponse, error)

GetSecret implements HostService.GetSecret

func (*HostServiceServer) ListAuthHandlers added in v0.8.0 

func (h *HostServiceServer) ListAuthHandlers(ctx context.Context, _ *proto.ListAuthHandlersRequest) (*proto.ListAuthHandlersResponse, error)

ListAuthHandlers implements HostService.ListAuthHandlers

func (*HostServiceServer) ListSecrets added in v0.8.0 

func (h *HostServiceServer) ListSecrets(ctx context.Context, req *proto.ListSecretsRequest) (*proto.ListSecretsResponse, error)

ListSecrets implements HostService.ListSecrets

func (*HostServiceServer) SetSecret added in v0.8.0 

func (h *HostServiceServer) SetSecret(ctx context.Context, req *proto.SetSecretRequest) (*proto.SetSecretResponse, error)

SetSecret implements HostService.SetSecret

type LoginRequest added in v0.5.0 

type LoginRequest = sdkplugin.LoginRequest

LoginRequest contains parameters for a plugin Login call.

type LoginResponse added in v0.5.0 

type LoginResponse = sdkplugin.LoginResponse

LoginResponse contains the result of a plugin Login call.

type LoginStreamMessage added in v0.5.0 

type LoginStreamMessage = sdkplugin.LoginStreamMessage

LoginStreamMessage represents a message in the Login server-stream.

type Pool added in v0.14.0 

type Pool struct {
	// contains filtered or unexported fields
}

Pool manages shared, long-lived plugin processes with lazy initialization and idle eviction. It is safe for concurrent use.

Official providers pre-loaded at startup can be added via Adopt; external plugins declared in bundle.plugins are loaded on-demand via Ensure.

func NewPool added in v0.14.0 

func NewPool(fetcher *Fetcher, registry *provider.Registry, logger logr.Logger, opts ...PoolOption) *Pool

NewPool creates a plugin pool backed by the given fetcher and registry. The fetcher may be nil if only Adopt (pre-loaded) plugins are used.

func (*Pool) Acquire added in v0.14.0 

func (p *Pool) Acquire(name string) bool

Acquire increments the reference count for a plugin, preventing eviction. Returns false if the plugin is not in the pool or is dead.

func (*Pool) Adopt added in v0.14.0 

func (p *Pool) Adopt(name string, client *Client, dep solution.PluginDependency, registeredProviders []string)

Adopt registers an already-running plugin client into the pool so that its lifecycle (idle eviction, shutdown) is managed by the pool. This is used for official providers pre-loaded at startup.

func (*Pool) ClientOptsLen added in v0.15.0 

func (p *Pool) ClientOptsLen() int

ClientOptsLen returns the number of extra client options configured on the pool. This is primarily useful for testing that WithClientOptions was wired correctly.

func (*Pool) Ensure added in v0.14.0 

func (p *Pool) Ensure(ctx context.Context, deps []solution.PluginDependency) error

Ensure guarantees that all plugins in deps are running and registered in the provider registry. For plugins already in the pool and healthy, this is a no-op. For new plugins, it fetches, spawns, and registers them.

func (*Pool) EnsureAndAcquire added in v0.14.0 

func (p *Pool) EnsureAndAcquire(ctx context.Context, deps []solution.PluginDependency) (release func(), err error)

EnsureAndAcquire ensures all plugins are available and acquires them (increments their refcounts), preventing idle eviction for the duration of the caller's work. Returns a release function that must be called when the caller is done using the plugins (typically via defer).

func (*Pool) Ping added in v0.14.0 

func (p *Pool) Ping(ctx context.Context, name string) bool

Ping checks if a plugin is alive by issuing a lightweight RPC.

func (*Pool) Release added in v0.14.0 

func (p *Pool) Release(name string)

Release decrements the reference count for a plugin.

func (*Pool) SanitizeEnv added in v0.15.0 

func (p *Pool) SanitizeEnv() bool

SanitizeEnv reports whether this pool sanitizes the environment for spawned plugin clients. See WithSanitizeEnv.

func (*Pool) Shutdown added in v0.14.0 

func (p *Pool) Shutdown()

Shutdown kills all managed plugin processes. Called once on server stop.

func (*Pool) Stats added in v0.14.0 

func (p *Pool) Stats() PoolStats

Stats returns current pool metrics.

type PoolOption added in v0.14.0 

type PoolOption func(*poolOptions)

PoolOption configures pool behavior.

func WithAllowedPlugins added in v0.14.0 

func WithAllowedPlugins(names []string) PoolOption

WithAllowedPlugins restricts which external plugins may be loaded via Ensure. Plugins not in this list are rejected with ErrPluginNotAllowed. A nil or empty list means all plugins are allowed (no restriction). Adopted (pre-loaded) plugins bypass this check.

func WithClientOptions added in v0.15.0 

func WithClientOptions(opts ...ClientOption) PoolOption

WithClientOptions sets additional ClientOption values that are passed to every plugin client spawned by the pool. Use this to inject host-side dependencies such as auth registries (via WithHostDeps).

func WithDisableExternal added in v0.14.0 

func WithDisableExternal(disabled bool) PoolOption

WithDisableExternal rejects all plugin load attempts via Ensure. Only pre-loaded (Adopt) plugins are usable. This is the safe default for API server deployments.

func WithHealthCheckInterval added in v0.14.0 

func WithHealthCheckInterval(d time.Duration) PoolOption

WithHealthCheckInterval sets the background health check frequency. Zero disables background checks (health is verified on use).

NOTE: Background health checks are not yet implemented. This option stores the interval for future use. Currently, dead plugins are only detected when a caller invokes Ping or when a request fails.

func WithIdleTimeout added in v0.14.0 

func WithIdleTimeout(d time.Duration) PoolOption

WithIdleTimeout sets how long an unused plugin stays alive before eviction. Zero disables idle eviction.

func WithMaxPlugins added in v0.14.0 

func WithMaxPlugins(n int) PoolOption

WithMaxPlugins sets the maximum number of external plugin processes. Zero means unlimited.

func WithSanitizeEnv added in v0.15.0 

func WithSanitizeEnv(sanitize bool) PoolOption

WithSanitizeEnv controls whether spawned plugin clients get a sanitized environment (true) or inherit the host environment (false). Defaults to true. API server deployments should use true; MCP interactive sessions may use false so plugins can access host credentials (SSH_AUTH_SOCK, tokens, etc.).

type PoolStats added in v0.14.0 

type PoolStats struct {
	Active  int // Entries with refCount > 0
	Idle    int // Entries in ready state with refCount == 0
	Dead    int // Entries that crashed and await eviction or re-spawn
	Total   int // All entries
	Evicted int // Cumulative evictions since pool creation
}

PoolStats holds pool metrics.

type ProviderConfig added in v0.8.0 

type ProviderConfig = sdkplugin.ProviderConfig

ProviderConfig holds host-side configuration sent to a provider once after plugin load via the ConfigureProvider RPC.

type ProviderPlugin 

type ProviderPlugin = sdkplugin.ProviderPlugin

ProviderPlugin is the interface that plugins must implement.

type ProviderWrapper 

type ProviderWrapper struct {
	// contains filtered or unexported fields
}

ProviderWrapper wraps a plugin provider to implement the provider.Provider interface

func NewProviderWrapper 

func NewProviderWrapper(client *Client, providerName string, opts ...WrapperOption) (*ProviderWrapper, error)

NewProviderWrapper creates a new provider wrapper for a plugin provider

func (*ProviderWrapper) Client 

func (w *ProviderWrapper) Client() *Client

Client returns the underlying plugin client

func (*ProviderWrapper) Configure added in v0.8.0 

func (w *ProviderWrapper) Configure(ctx context.Context, cfg ProviderConfig) error

Configure sends host-side configuration to the plugin provider. This should be called once after wrapper creation, before any Execute calls.

func (*ProviderWrapper) Descriptor 

func (w *ProviderWrapper) Descriptor() *provider.Descriptor

Descriptor returns the provider descriptor

func (*ProviderWrapper) Execute 

func (w *ProviderWrapper) Execute(ctx context.Context, input any) (*provider.Output, error)

Execute executes the provider. When IOStreams are present in the context, it attempts to use streaming execution so that incremental output (e.g. from exec-like providers) reaches the terminal in real time. Falls back to the unary RPC when the plugin does not support streaming.

Streaming error contract: the GRPCClient.ExecuteProviderStream callback receives stdout/stderr chunks as they arrive. Terminal errors are delivered in two ways: (1) the callback receives a chunk with Error set, and (2) ExecuteProviderStream returns a non-nil error. This wrapper checks the return value first — if it signals ErrStreamingNotSupported it falls back to unary; for other errors it returns immediately. When the stream completes successfully (nil return), any chunk-level error is surfaced.

func (*ProviderWrapper) ExecuteStream added in v0.8.0 

func (w *ProviderWrapper) ExecuteStream(ctx context.Context, input any, cb func(StreamChunk)) error

ExecuteStream executes the provider with streaming output. The callback receives chunks as they arrive from the plugin.

type SignatureMode added in v0.15.0 

type SignatureMode string

SignatureMode controls how signature verification failures are handled. 

const (
	// SignatureModeOff disables signature verification entirely (digest-only).
	SignatureModeOff SignatureMode = "off"

	// SignatureModeWarn verifies signatures but logs a warning on failure
	// instead of blocking execution.
	SignatureModeWarn SignatureMode = "warn"

	// SignatureModeEnforce requires valid signatures; missing or invalid
	// signatures cause a hard failure.
	SignatureModeEnforce SignatureMode = "enforce"
)

func ParseSignatureMode added in v0.15.0 

func ParseSignatureMode(s string) (SignatureMode, error)

ParseSignatureMode converts a string to a SignatureMode, returning an error for unrecognized values.

type SignaturePolicy added in v0.15.0 

type SignaturePolicy struct {
	// Mode controls behavior on verification failure.
	Mode SignatureMode `json:"mode" yaml:"mode" doc:"Signature verification mode" enum:"off,warn,enforce" example:"warn"`

	// TrustedIssuers are OIDC issuers whose signing certificates are trusted
	// (e.g., "https://token.actions.githubusercontent.com").
	TrustedIssuers []string `json:"trustedIssuers,omitempty" yaml:"trustedIssuers,omitempty" doc:"Trusted OIDC certificate issuers" maxItems:"20"`

	// TrustedIdentities are glob patterns matching the certificate
	// subject/identity (e.g., "https://github.com/oakwood-commons/*").
	TrustedIdentities []string `` /* 130-byte string literal not displayed */
}

SignaturePolicy defines the verification policy for plugin binary signatures.

func SignaturePolicyFromContext added in v0.15.0 

func SignaturePolicyFromContext(ctx context.Context) *SignaturePolicy

SignaturePolicyFromContext retrieves the SignaturePolicy from the context. Returns nil if none is set.

func SignaturePolicyFromRaw added in v0.15.0 

func SignaturePolicyFromRaw(mode string, trustedIssuers, trustedIdentities []string) (*SignaturePolicy, error)

SignaturePolicyFromRaw constructs a SignaturePolicy from raw configuration values. Returns (nil, nil) when mode is "off" or empty. Returns an error for unrecognized mode values.

func (*SignaturePolicy) IsEnabled added in v0.15.0 

func (p *SignaturePolicy) IsEnabled() bool

IsEnabled reports whether signature verification is active (mode != off). An empty Mode is treated as off (consistent with ParseSignatureMode).

func (*SignaturePolicy) Validate added in v0.15.0 

func (p *SignaturePolicy) Validate() error

Validate checks the policy for configuration errors. It returns an error when the mode requires verification but no trusted issuer/identity pairs are configured.

type SignatureResult added in v0.15.0 

type SignatureResult struct {
	// Verified is true when a valid signature was confirmed.
	Verified bool `json:"verified" yaml:"verified" doc:"Whether a valid signature was confirmed"`

	// Issuer is the OIDC issuer from the signing certificate.
	Issuer string `` /* 147-byte string literal not displayed */

	// Identity is the certificate subject/identity.
	Identity string `` /* 221-byte string literal not displayed */

	// SignedAt is the signature timestamp in RFC 3339 format (empty if unknown).
	SignedAt string `` /* 249-byte string literal not displayed */
}

SignatureResult holds the outcome of a signature verification attempt.

type SignatureVerifier added in v0.15.0 

type SignatureVerifier interface {
	// VerifySignature checks the Sigstore/cosign signature for an OCI artifact
	// identified by its image reference (registry/repo@digest).
	// Returns the verification result or an error if verification could not
	// be performed (network failure, missing cosign support, etc.).
	VerifySignature(ctx context.Context, imageRef string, policy *SignaturePolicy) (*SignatureResult, error)
}

SignatureVerifier verifies OCI artifact signatures.

func NewSignatureVerifier added in v0.15.0 

func NewSignatureVerifier() SignatureVerifier

NewSignatureVerifier returns a stub verifier when the cosign build tag is not present. The stub returns ErrCosignNotAvailable only when verification is requested (policy is non-nil and enabled).

type StreamChunk added in v0.8.0 

type StreamChunk = sdkplugin.StreamChunk

StreamChunk represents one chunk from a streaming provider execution.

type TokenRequest added in v0.5.0 

type TokenRequest = sdkplugin.TokenRequest

TokenRequest contains parameters for a plugin GetToken call.

type TokenResponse added in v0.5.0 

type TokenResponse = sdkplugin.TokenResponse

TokenResponse contains the result of a plugin GetToken call.

type WrapperOption added in v0.8.0 

type WrapperOption func(*wrapperConfig)

WrapperOption configures NewProviderWrapper.

func WithContext added in v0.8.0 

func WithContext(ctx context.Context) WrapperOption

WithContext sets the context used during wrapper initialisation (e.g. for the initial GetProviderDescriptor RPC). Defaults to context.Background(). A nil context is silently replaced with context.Background().

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.