pluginloader

package
v3.1.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2026 License: GPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package pluginloader verifies native plugin artifacts before loading them.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrArtifactUnavailable is returned when a verified handoff path is not openable anymore.
	ErrArtifactUnavailable = errors.New("plugin artifact unavailable after verification")

	// ErrPluginOpenFailed is returned when plugin.Open fails.
	ErrPluginOpenFailed = errors.New("plugin open failed")

	// ErrFactorySymbolMissing is returned when the plugin factory symbol cannot be resolved.
	ErrFactorySymbolMissing = errors.New("plugin factory symbol missing")

	// ErrFactorySymbolInvalid is returned when the factory has the wrong Go type.
	ErrFactorySymbolInvalid = errors.New("plugin factory symbol has invalid type")

	// ErrFactoryFailed is returned when the factory returns an error.
	ErrFactoryFailed = errors.New("plugin factory failed")

	// ErrNilPlugin is returned when the factory returns a nil plugin.
	ErrNilPlugin = errors.New("plugin factory returned nil plugin")

	// ErrPluginPanic is returned when a host-invoked plugin method panics.
	ErrPluginPanic = errors.New("plugin panicked")

	// ErrRequiredModuleFailed is returned when a required module cannot be registered.
	ErrRequiredModuleFailed = errors.New("required plugin module failed")
)
View Source 
var (
	// ErrArtifactOutsideAllowedDirs is returned when a resolved artifact escapes the configured allowlist.
	ErrArtifactOutsideAllowedDirs = errors.New("plugin artifact outside allowed directories")

	// ErrChecksumMismatch is returned when the artifact digest differs from the configured checksum.
	ErrChecksumMismatch = errors.New("plugin checksum mismatch")

	// ErrSignatureVerificationFailed is returned when a detached artifact signature cannot be verified.
	ErrSignatureVerificationFailed = errors.New("plugin signature verification failed")
)
View Source 
var (
	// ErrOrderedPluginBackendMissing reports an auth.backends.order plugin selector
	// that did not resolve to a registered backend component.
	ErrOrderedPluginBackendMissing = errors.New("ordered plugin backend is not registered")
)
View Source 
var (
	// ErrPluginDebugSelectorMissing reports an exact debug selector without a registered module.
	ErrPluginDebugSelectorMissing = errors.New("plugin debug selector is not registered")
)

Functions

func DefaultPluginSigningKeyID 

func DefaultPluginSigningKeyID(publicKey ed25519.PublicKey) ([]byte, error)

DefaultPluginSigningKeyID derives the minisign-compatible key id used for Nauthilus plugin signatures.

func FormatMinisignSignature 

func FormatMinisignSignature(artifactPath string, privateKey ed25519.PrivateKey, keyID []byte, trustedComment string) ([]byte, error)

FormatMinisignSignature builds a minisign-style detached signature for an artifact.

func FormatPluginPublicKey 

func FormatPluginPublicKey(publicKey ed25519.PublicKey, keyID []byte, comment string) ([]byte, error)

FormatPluginPublicKey formats an Ed25519 public key in minisign/signify-compatible text form.

func ParsePluginSigningPrivateKey 

func ParsePluginSigningPrivateKey(raw []byte) (ed25519.PrivateKey, error)

ParsePluginSigningPrivateKey decodes a base64 Ed25519 seed or private key for build-time signing.

func SetDefaultState 

func SetDefaultState(state *State)

SetDefaultState publishes the most recent plugin loader state for later runtime wiring.

func ValidateOrderedPluginBackends 

func ValidateOrderedPluginBackends(cfg config.File, state *State) error

ValidateOrderedPluginBackends verifies that auth.backends.order plugin entries refer to registered backend components after native plugin registration.

func ValidatePluginDebugSelectors 

func ValidatePluginDebugSelectors(cfg config.File, state *State) error

ValidatePluginDebugSelectors verifies exact plugin debug selectors after module registration.

func WriteMinisignSignatureFile 

func WriteMinisignSignatureFile(artifactPath string, signaturePath string, privateKey ed25519.PrivateKey, keyID []byte, trustedComment string) error

WriteMinisignSignatureFile writes a minisign-style detached signature for an artifact.

Types

type DiscoveryCompatibility 

type DiscoveryCompatibility struct {
	Metrics     []DiscoveryCompatibilityMetric `json:"metrics,omitempty"`
	TraceScopes []string                       `json:"trace_scopes,omitempty"`
}

DiscoveryCompatibility exposes restart-only exact observability allowlists without secrets.

type DiscoveryCompatibilityMetric 

type DiscoveryCompatibilityMetric struct {
	Buckets []float64            `json:"buckets,omitempty"`
	Labels  []string             `json:"labels,omitempty"`
	Type    pluginapi.MetricType `json:"type"`
	Name    string               `json:"name"`
	Help    string               `json:"help"`
}

DiscoveryCompatibilityMetric exposes one exact collector contract.

type DiscoveryComponent 

type DiscoveryComponent struct {
	Source        *DiscoverySourceDescriptor     `json:"source,omitempty"`
	Hook          *DiscoveryHookDescriptor       `json:"hook,omitempty"`
	QualifiedName string                         `json:"qualified_name"`
	ModuleName    string                         `json:"module_name"`
	Name          string                         `json:"name"`
	Kind          pluginregistry.ComponentKind   `json:"kind"`
	Origin        pluginregistry.ComponentOrigin `json:"origin"`
}

DiscoveryComponent describes one registered component descriptor.

type DiscoveryDebugModule 

type DiscoveryDebugModule struct {
	Selector    string                         `json:"selector"`
	ModuleName  string                         `json:"module_name"`
	Name        string                         `json:"name,omitempty"`
	Description string                         `json:"description,omitempty"`
	Origin      pluginregistry.ComponentOrigin `json:"origin"`
}

DiscoveryDebugModule describes one registered plugin debug selector.

type DiscoveryDocument 

type DiscoveryDocument struct {
	Modules []DiscoveryModule `json:"modules"`
}

DiscoveryDocument is a machine-readable snapshot of registered native plugins.

type DiscoveryHookDescriptor 

type DiscoveryHookDescriptor struct {
	RequiredScopes []string            `json:"required_scopes,omitempty"`
	Name           string              `json:"name"`
	Method         string              `json:"method"`
	Path           string              `json:"path"`
	Alias          string              `json:"alias,omitempty"`
	Scope          pluginapi.HookScope `json:"scope"`
	Auth           pluginapi.HookAuth  `json:"auth"`
	Timeout        time.Duration       `json:"timeout"`
	MaxBodyBytes   int64               `json:"max_body_bytes"`
}

DiscoveryHookDescriptor describes HTTP hook routing metadata.

type DiscoveryMetadata 

type DiscoveryMetadata struct {
	Build        pluginapi.BuildInfo    `json:"build"`
	Name         string                 `json:"name,omitempty"`
	Version      string                 `json:"version,omitempty"`
	APIVersion   string                 `json:"api_version,omitempty"`
	Description  string                 `json:"description,omitempty"`
	DocsURL      string                 `json:"docs_url,omitempty"`
	Features     []pluginapi.Feature    `json:"features,omitempty"`
	Capabilities []pluginapi.Capability `json:"capabilities,omitempty"`
}

DiscoveryMetadata exposes plugin product metadata and build diagnostics.

type DiscoveryModule 

type DiscoveryModule struct {
	Metadata             DiscoveryMetadata      `json:"metadata"`
	Components           []DiscoveryComponent   `json:"components,omitempty"`
	DebugModules         []DiscoveryDebugModule `json:"debug_modules,omitempty"`
	Compatibility        DiscoveryCompatibility `json:"compatibility,omitempty"`
	RequiredCapabilities []pluginapi.Capability `json:"required_capabilities,omitempty"`
	Name                 string                 `json:"name"`
	Type                 string                 `json:"type,omitempty"`
	Status               ModuleStatus           `json:"status"`
	ArtifactPath         string                 `json:"artifact_path,omitempty"`
	Signer               string                 `json:"signer,omitempty"`
	VerifiedSigner       string                 `json:"verified_signer,omitempty"`
	FailureStep          string                 `json:"failure_step,omitempty"`
	Optional             bool                   `json:"optional"`
	ChecksumConfigured   bool                   `json:"checksum_configured"`
	SignatureConfigured  bool                   `json:"signature_configured"`
	SignatureVerified    bool                   `json:"signature_verified"`
}

DiscoveryModule describes one configured plugin module without plugin-owned config.

type DiscoverySourceDescriptor 

type DiscoverySourceDescriptor struct {
	Requires    []string              `json:"requires,omitempty"`
	After       []string              `json:"after,omitempty"`
	Name        string                `json:"name"`
	Timeout     time.Duration         `json:"timeout"`
	Priority    int                   `json:"priority"`
	AbortPolicy pluginapi.AbortPolicy `json:"abort_policy"`
}

DiscoverySourceDescriptor describes dependency-scheduled source metadata.

type Loader 

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

Loader opens verified artifacts and records registered module instances.

func NewLoader 

func NewLoader(options ...Option) *Loader

NewLoader returns a plugin loader with production defaults.

func (*Loader) Load 

func (l *Loader) Load(verified []VerifiedModule) (*State, error)

Load opens, validates, and registers verified module artifacts.

type ModuleError 

type ModuleError struct {
	Err          error
	ModuleName   string
	ArtifactPath string
	Step         string
}

ModuleError annotates a module load error with an operator-readable step.

func (*ModuleError) Error 

func (e *ModuleError) Error() string

Error describes the failed module step without exposing plugin-owned config.

func (*ModuleError) Unwrap 

func (e *ModuleError) Unwrap() error

Unwrap returns the underlying module error.

type ModuleInstance 

type ModuleInstance struct {
	Plugin            pluginapi.Plugin
	RegistrationError error
	Metadata          pluginapi.Metadata
	Module            config.PluginModule
	Descriptors       []pluginregistry.Component
	DebugModules      []pluginregistry.DebugModule
	Capabilities      []pluginapi.Capability
	ArtifactPath      string
	SignaturePath     string
	VerifiedSigner    string
	ModuleName        string
	Status            ModuleStatus
	Optional          bool
}

ModuleInstance stores the host-visible state for one configured plugin module.

func (ModuleInstance) IsRegistered 

func (m ModuleInstance) IsRegistered() bool

IsRegistered reports whether the instance can participate in the plugin runtime.

type ModuleStatus 

type ModuleStatus string

ModuleStatus describes the registration state for one configured module. 

const (
	// ModuleStatusRegistered marks a module whose factory, metadata, and Register call succeeded.
	ModuleStatusRegistered ModuleStatus = "registered"

	// ModuleStatusFailed marks a module whose startup-time registration path failed.
	ModuleStatusFailed ModuleStatus = "failed"
)

type Opener 

type Opener interface {
	Open(path string) (PluginHandle, error)
}

Opener opens an already verified plugin artifact path.

type Option 

type Option func(*Loader)

Option configures a Loader.

func WithLogger 

func WithLogger(logger *slog.Logger) Option

WithLogger configures operator-visible optional module logging.

func WithOpener 

func WithOpener(opener Opener) Option

WithOpener injects an opener, primarily for fake-backed loader tests.

type PluginHandle 

type PluginHandle interface {
	Lookup(symbol string) (any, error)
}

PluginHandle resolves symbols from one opened plugin artifact.

type State 

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

State contains all module instances registered during one loader run.

func DefaultState 

func DefaultState() (*State, bool)

DefaultState returns the most recent plugin loader state, if any.

func (*State) Discovery 

func (s *State) Discovery() DiscoveryDocument

Discovery returns registered native plugin metadata and component descriptors.

func (*State) Instances 

func (s *State) Instances() []ModuleInstance

Instances returns module instance state in configured order.

func (*State) Registry 

func (s *State) Registry() *pluginregistry.Registry

Registry returns the component registry created by the loader run.

type VerifiedModule 

type VerifiedModule struct {
	Module        config.PluginModule
	Signer        *config.PluginTrustSigner
	ArtifactPath  string
	SignaturePath string
}

VerifiedModule describes a module whose loader-owned artifact checks completed.

type Verifier 

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

Verifier validates configured plugin artifacts before plugin.Open is allowed.

func NewVerifier 

func NewVerifier(options ...VerifierOption) Verifier

NewVerifier returns the default plugin artifact verifier.

func (Verifier) Verify 

func (v Verifier) Verify(plugins *config.PluginsSection) ([]VerifiedModule, error)

Verify validates all configured plugin artifacts and returns canonical paths.

type VerifierOption 

type VerifierOption func(*Verifier)

VerifierOption customizes artifact verification.

func WithVerificationLogger 

func WithVerificationLogger(logger *slog.Logger) VerifierOption

WithVerificationLogger configures structured artifact verification logging.

Source Files

View all Source files

Directories

Path Synopsis
cmd
nauthilus-plugin-sign command
Command nauthilus-plugin-sign creates and signs native plugin distribution keys.
 Command nauthilus-plugin-sign creates and signs native plugin distribution keys.

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.