plugin

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 27, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package plugin provides the shared contract between scafctl (host) and plugin binaries. Plugin authors implement ProviderPlugin and/or AuthHandlerPlugin, then call Serve() or ServeAuthHandler() from main().

Index

Constants

View Source 
const (
	PluginName            = "provider"
	AuthHandlerPluginName = "auth-handler"
)
View Source 
const PluginProtocolVersion int32 = 2

PluginProtocolVersion is the current plugin protocol version.

Variables

View Source 
var ErrStreamingNotSupported = errors.New("streaming execution not supported")

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

Functions

func ProtoToDescriptor 

func ProtoToDescriptor(pd *proto.ProviderDescriptor) (*provider.Descriptor, error)

ProtoToDescriptor converts proto.ProviderDescriptor to provider.Descriptor.

func Serve 

func Serve(impl ProviderPlugin)

Serve is a helper function for plugin implementers to serve their provider plugins.

func ServeAuthHandler 

func ServeAuthHandler(impl AuthHandlerPlugin)

ServeAuthHandler is a helper function for plugin implementers to serve their auth handler plugins.

func WithHostClient added in v0.3.0 

func WithHostClient(ctx context.Context, client *HostServiceClient) context.Context

WithHostClient returns a new context with the given HostServiceClient attached.

Types

type AuthHandlerGRPCClient 

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

AuthHandlerGRPCClient is a minimal stub auth handler client.

func (*AuthHandlerGRPCClient) Client 

func (c *AuthHandlerGRPCClient) Client() proto.AuthHandlerServiceClient

Client returns the underlying AuthHandlerServiceClient for host-side wrapping.

type AuthHandlerGRPCPlugin 

type AuthHandlerGRPCPlugin struct {
	goplugin.Plugin
	Impl AuthHandlerPlugin
}

AuthHandlerGRPCPlugin implements plugin.GRPCPlugin for auth handler plugins.

func (*AuthHandlerGRPCPlugin) GRPCClient 

func (p *AuthHandlerGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)

GRPCClient returns a minimal stub client for auth handler plugins.

func (*AuthHandlerGRPCPlugin) GRPCServer 

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

GRPCServer registers the auth handler gRPC server.

type AuthHandlerGRPCServer 

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

AuthHandlerGRPCServer implements the gRPC server for auth handler plugins.

func (*AuthHandlerGRPCServer) ConfigureAuthHandler 

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

func (*AuthHandlerGRPCServer) GetAuthHandlers 

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

func (*AuthHandlerGRPCServer) GetStatus 

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

func (*AuthHandlerGRPCServer) GetToken 

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

func (*AuthHandlerGRPCServer) ListCachedTokens 

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

func (*AuthHandlerGRPCServer) Login 

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

func (*AuthHandlerGRPCServer) Logout 

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

func (*AuthHandlerGRPCServer) PurgeExpiredTokens 

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

func (*AuthHandlerGRPCServer) StopAuthHandler 

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

type AuthHandlerInfo 

type AuthHandlerInfo struct {
	Name         string            `json:"name" yaml:"name"`
	DisplayName  string            `json:"displayName" yaml:"displayName"`
	Flows        []auth.Flow       `json:"flows" yaml:"flows"`
	Capabilities []auth.Capability `json:"capabilities" yaml:"capabilities"`
}

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

type AuthHandlerPlugin 

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, deviceCodeCb 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
}

AuthHandlerPlugin is the interface that auth handler plugins must implement.

type DeviceCodePrompt 

type DeviceCodePrompt struct {
	UserCode        string `json:"userCode" yaml:"userCode"`
	VerificationURI string `json:"verificationUri" yaml:"verificationUri"`
	Message         string `json:"message" yaml:"message"`
}

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

type GRPCClient 

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

GRPCClient is a minimal stub provider plugin client.

func (*GRPCClient) Client 

func (c *GRPCClient) Client() proto.PluginServiceClient

Client returns the underlying PluginServiceClient for host-side wrapping.

type GRPCPlugin 

type GRPCPlugin struct {
	goplugin.Plugin
	Impl ProviderPlugin
}

GRPCPlugin implements plugin.GRPCPlugin from hashicorp/go-plugin.

func (*GRPCPlugin) GRPCClient 

func (p *GRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)

GRPCClient returns a minimal stub client. The host wraps this with its own extended GRPCClient that adds broker wiring and HostService startup.

func (*GRPCPlugin) GRPCServer 

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

GRPCServer registers the gRPC server (plugin side).

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 

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

func (*GRPCServer) DescribeWhatIf 

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

func (*GRPCServer) ExecuteProvider 

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

func (*GRPCServer) ExecuteProviderStream 

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

func (*GRPCServer) ExtractDependencies 

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

func (*GRPCServer) GetProviderDescriptor 

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

func (*GRPCServer) GetProviders 

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

func (*GRPCServer) StopProvider 

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

type HandshakeConfigData 

type HandshakeConfigData struct {
	ProtocolVersion  uint   `json:"protocolVersion" yaml:"protocolVersion"`
	MagicCookieKey   string `json:"magicCookieKey" yaml:"magicCookieKey"`
	MagicCookieValue string `json:"magicCookieValue" yaml:"magicCookieValue"`
}

HandshakeConfigData contains the handshake configuration.

func AuthHandlerHandshakeConfig 

func AuthHandlerHandshakeConfig() HandshakeConfigData

AuthHandlerHandshakeConfig returns the handshake configuration for auth handler plugin compatibility. Returns a copy to prevent mutation of shared state.

func HandshakeConfig 

func HandshakeConfig() HandshakeConfigData

HandshakeConfig returns the handshake configuration for provider plugin compatibility. Returns a copy to prevent mutation of shared state.

type HostServiceClient 

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

HostServiceClient wraps the HostService gRPC client (used by plugins).

func HostClientFromContext added in v0.3.0 

func HostClientFromContext(ctx context.Context) *HostServiceClient

HostClientFromContext retrieves the HostServiceClient from the context. Returns nil if no host client is available (e.g. the host did not start a HostService broker).

func NewHostServiceClient 

func NewHostServiceClient(conn *grpc.ClientConn) *HostServiceClient

NewHostServiceClient creates a HostServiceClient from a gRPC connection.

func (*HostServiceClient) DeleteSecret 

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.4.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. Handlers that implement group queries (e.g. Entra) may return memberships. If the selected handler does not support group queries, this method returns an empty slice and a nil error.

func (*HostServiceClient) GetAuthIdentity 

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 

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 

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 

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

ListAuthHandlers lists available auth handlers on the host.

func (*HostServiceClient) ListSecrets 

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

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

func (*HostServiceClient) SetSecret 

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

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

type LoginRequest 

type LoginRequest struct {
	TenantID string        `json:"tenantId,omitempty" yaml:"tenantId,omitempty"`
	Scopes   []string      `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	Flow     auth.Flow     `json:"flow,omitempty" yaml:"flow,omitempty"`
	Timeout  time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
}

LoginRequest contains parameters for a plugin Login call.

type LoginResponse 

type LoginResponse struct {
	Claims    *auth.Claims `json:"claims,omitempty" yaml:"claims,omitempty"`
	ExpiresAt time.Time    `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty"`
}

LoginResponse contains the result of a plugin Login call.

type LoginStreamMessage 

type LoginStreamMessage struct {
	DeviceCodePrompt *DeviceCodePrompt `json:"deviceCodePrompt,omitempty" yaml:"deviceCodePrompt,omitempty"`
	Result           *LoginResponse    `json:"result,omitempty" yaml:"result,omitempty"`
	Error            string            `json:"error,omitempty" yaml:"error,omitempty"`
}

LoginStreamMessage represents a message in the Login server-stream.

type ProviderConfig 

type ProviderConfig struct {
	Quiet         bool                       `json:"quiet" yaml:"quiet"`
	NoColor       bool                       `json:"noColor" yaml:"noColor"`
	BinaryName    string                     `json:"binaryName" yaml:"binaryName"`
	HostServiceID uint32                     `json:"hostServiceId,omitempty" yaml:"hostServiceId,omitempty"`
	Settings      map[string]json.RawMessage `json:"settings,omitempty" yaml:"settings,omitempty"`
}

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

type ProviderPlugin 

type ProviderPlugin interface {
	GetProviders(ctx context.Context) ([]string, error)
	GetProviderDescriptor(ctx context.Context, providerName string) (*provider.Descriptor, error)
	ConfigureProvider(ctx context.Context, providerName string, cfg ProviderConfig) error
	ExecuteProvider(ctx context.Context, providerName string, input map[string]any) (*provider.Output, error)
	ExecuteProviderStream(ctx context.Context, providerName string, input map[string]any, cb func(StreamChunk)) error
	DescribeWhatIf(ctx context.Context, providerName string, input map[string]any) (string, error)
	ExtractDependencies(ctx context.Context, providerName string, inputs map[string]any) ([]string, error)
	StopProvider(ctx context.Context, providerName string) error
}

ProviderPlugin is the interface that plugins must implement.

type StreamChunk 

type StreamChunk struct {
	Stdout []byte           `json:"stdout,omitempty" yaml:"stdout,omitempty"`
	Stderr []byte           `json:"stderr,omitempty" yaml:"stderr,omitempty"`
	Result *provider.Output `json:"result,omitempty" yaml:"result,omitempty"`
	Error  string           `json:"error,omitempty" yaml:"error,omitempty"`
}

StreamChunk represents one chunk from a streaming provider execution.

type TokenRequest 

type TokenRequest struct {
	Scope        string        `json:"scope,omitempty" yaml:"scope,omitempty"`
	MinValidFor  time.Duration `json:"minValidFor,omitempty" yaml:"minValidFor,omitempty"`
	ForceRefresh bool          `json:"forceRefresh,omitempty" yaml:"forceRefresh,omitempty"`
}

TokenRequest contains parameters for a plugin GetToken call.

type TokenResponse 

type TokenResponse struct {
	AccessToken string    `json:"accessToken" yaml:"accessToken"` //nolint:gosec
	TokenType   string    `json:"tokenType" yaml:"tokenType"`
	ExpiresAt   time.Time `json:"expiresAt" yaml:"expiresAt"`
	Scope       string    `json:"scope,omitempty" yaml:"scope,omitempty"`
	CachedAt    time.Time `json:"cachedAt,omitempty" yaml:"cachedAt,omitempty"`
	Flow        auth.Flow `json:"flow,omitempty" yaml:"flow,omitempty"`
	SessionID   string    `json:"sessionId,omitempty" yaml:"sessionId,omitempty"`
}

TokenResponse contains the result of a plugin GetToken call.

Source Files

View all Source files

Directories

Path Synopsis

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.