pluginloader

package
v3.1.0-beta.15 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 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")
)

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 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 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 DiscoveryDocument 

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

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

type DiscoveryHookDescriptor 

type DiscoveryHookDescriptor struct {
	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"`
	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"`
	FailureStep          string                 `json:"failure_step,omitempty"`
	Optional             bool                   `json:"optional"`
	ChecksumConfigured   bool                   `json:"checksum_configured"`
	SignatureConfigured  bool                   `json:"signature_configured"`
}

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
	Capabilities      []pluginapi.Capability
	ArtifactPath      string
	SignaturePath     string
	ModuleName        string
	Status            ModuleStatus
	Optional          bool
}

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

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.