componenttypes

package
v0.1.12 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package componenttypes defines shared types for component management. These types are used across lockfile, userconfig, catalog, and conformance packages to provide a consistent interface for component metadata.

Package componenttypes defines shared types for component management. This file defines exit codes and error codes shared across all component types.

Package componenttypes defines shared types for component management. This file defines type-safe validated names that can only be constructed through validation functions, making validation bypass impossible.

Package componenttypes defines shared types for component management. This file defines binary name prefixes per C-001 naming convention.

Package componenttypes defines shared types for component management. This file defines verification options shared across all component types.

Index

Constants

View Source 
const (
	// CollectorProtocolVersion is the current collector protocol version.
	CollectorProtocolVersion = 1

	// ToolProtocolVersion is the current tool protocol version.
	ToolProtocolVersion = 1

	// RemoteProtocolVersion is the current remote adapter protocol version.
	RemoteProtocolVersion = 1
)

Protocol versions for each component type.

View Source 
const (
	// ExitConfigError indicates a configuration error (invalid config, missing required fields).
	ExitConfigError = 2

	// ExitAuthError indicates an authentication error (invalid credentials, expired token).
	ExitAuthError = 3

	// ExitNetworkError indicates a network/API error (connection failed, timeout, HTTP error).
	ExitNetworkError = 4
)

Component-specific exit codes (2-9). These are used by components to indicate specific error conditions. See C-022 in component-rules.md.

View Source 
const (
	// ExitComponentNotFound indicates the component binary was not found.
	// For tools: not in lockfile or PATH
	// For utilities: not installed
	// For collectors/remotes: not configured or binary missing
	ExitComponentNotFound = 10

	// ExitVerifyFailed indicates digest verification failed.
	// The binary exists but its digest doesn't match the lockfile.
	ExitVerifyFailed = 11

	// ExitPackVerifyFailed indicates pack integrity verification failed.
	// Used by tools that require a pack.
	ExitPackVerifyFailed = 12

	// ExitLockfileMissing indicates the lockfile is missing or invalid.
	ExitLockfileMissing = 13

	// ExitRunDirFailed indicates run directory creation failed.
	// Used by tool protocol when the wrapper can't create the run directory.
	ExitRunDirFailed = 14

	// ExitConfigFailed indicates configuration file write/read failed.
	ExitConfigFailed = 15

	// ExitPackRequired indicates a pack is required but not provided.
	ExitPackRequired = 16

	// ExitDependencyMissing indicates a required dependency is missing.
	ExitDependencyMissing = 17
)

Component wrapper exit codes (10-19). These are used consistently across all component types (tools, collectors, remotes, utilities).

View Source 
const (
	// ErrCodeComponentNotFound indicates the component was not found.
	ErrCodeComponentNotFound = "COMPONENT_NOT_FOUND"

	// ErrCodeVerifyFailed indicates digest verification failed.
	ErrCodeVerifyFailed = "VERIFICATION_FAILED"

	// ErrCodePackVerifyFailed indicates pack verification failed.
	ErrCodePackVerifyFailed = "PACK_VERIFICATION_FAILED"

	// ErrCodePackRequired indicates a pack is required but not provided.
	ErrCodePackRequired = "PACK_REQUIRED"

	// ErrCodeComponentFailed indicates the component execution failed.
	ErrCodeComponentFailed = "COMPONENT_FAILED"

	// ErrCodeComponentKilled indicates the component was killed (timeout, signal).
	ErrCodeComponentKilled = "COMPONENT_KILLED"

	// ErrCodeResultMissing indicates result.json was not written.
	ErrCodeResultMissing = "RESULT_MISSING"

	// ErrCodeResultInvalid indicates result.json is invalid.
	ErrCodeResultInvalid = "RESULT_INVALID"

	// ErrCodeInvalidOutput indicates an output path is invalid.
	ErrCodeInvalidOutput = "INVALID_OUTPUT_PATH"

	// ErrCodeRunDirFailed indicates run directory creation failed.
	ErrCodeRunDirFailed = "RUN_DIR_FAILED"

	// ErrCodeLockfileError indicates a lockfile error (missing, parse error, etc).
	ErrCodeLockfileError = "LOCKFILE_ERROR"

	// ErrCodeConfigFailed indicates config file write/read failed.
	ErrCodeConfigFailed = "CONFIG_WRITE_FAILED"

	// ErrCodeNotInLockfile indicates the component is not in the lockfile.
	ErrCodeNotInLockfile = "NOT_IN_LOCKFILE"

	// ErrCodePlatformNotInLockfile indicates the platform is not in lockfile.
	ErrCodePlatformNotInLockfile = "PLATFORM_NOT_IN_LOCKFILE"

	// ErrCodeDigestMissing indicates digest is missing from lockfile.
	ErrCodeDigestMissing = "DIGEST_MISSING"

	// ErrCodeDependencyMissing indicates a required dependency is missing.
	ErrCodeDependencyMissing = "DEPENDENCY_MISSING"
)

Component error codes for structured errors. These are used in result.json and error responses across all component types.

View Source 
const (
	// CollectorBinaryPrefix is the prefix for collector binaries.
	CollectorBinaryPrefix = "epack-collector-"

	// ToolBinaryPrefix is the prefix for tool binaries.
	ToolBinaryPrefix = "epack-tool-"

	// RemoteBinaryPrefix is the prefix for remote adapter binaries.
	RemoteBinaryPrefix = "epack-remote-"

	// UtilityBinaryPrefix is the prefix for utility binaries.
	UtilityBinaryPrefix = "epack-util-"
)

Binary name prefixes per C-001 naming convention. All component binaries must use these prefixes for discovery.

View Source 
const InsecureAllowUnpinnedEnvVar = "EPACK_INSECURE_ALLOW_UNPINNED"

InsecureAllowUnpinnedEnvVar is the environment variable that allows unpinned component execution when set to "true" or "1".

Variables

This section is empty.

Functions

func BinaryName 

func BinaryName(kind ComponentKind, name string) string

BinaryName returns the full binary name for a component.

func BinaryPrefix 

func BinaryPrefix(kind ComponentKind) string

BinaryPrefix returns the binary name prefix for the given component kind.

func CheckSecurity 

func CheckSecurity(kind ComponentKind, name string, info DigestInfo, opts VerifyOptions) error

CheckSecurity validates that execution is allowed given the digest info and options. Returns nil if execution is allowed, or an error describing the security violation.

The check order is:

  1. PATH-based components: allowed only with InsecureAllowUnpinned, never in frozen mode
  2. Missing digest: allowed only with InsecureAllowUnpinned, never in frozen mode
  3. Frozen mode: all components must have a digest

func CopyPlatforms 

func CopyPlatforms(src map[string]LockedPlatform) map[string]LockedPlatform

CopyPlatforms creates a defensive copy of a platforms map.

func InsecureAllowUnpinnedFromEnv 

func InsecureAllowUnpinnedFromEnv() bool

InsecureAllowUnpinnedFromEnv returns true if the environment variable EPACK_INSECURE_ALLOW_UNPINNED is set to "true" or "1".

func WarnUnpinnedExecution 

func WarnUnpinnedExecution(w io.Writer, kind ComponentKind, name, path string, fromPATH bool)

WarnUnpinnedExecution prints a warning when executing an unpinned component. This is called when InsecureAllowUnpinned is true and a component is not pinned.

Types

type CollectorName 

type CollectorName string

CollectorName is a validated collector name safe for filesystem paths. Can only be constructed via ParseCollectorName.

func MustParseCollectorName 

func MustParseCollectorName(name string) CollectorName

MustParseCollectorName parses a collector name, panicking on invalid input. Use only for compile-time constants or test fixtures.

func ParseCollectorName 

func ParseCollectorName(name string) (CollectorName, error)

ParseCollectorName validates and returns a CollectorName. Returns an error if the name contains path traversal patterns or invalid characters.

func (CollectorName) String 

func (n CollectorName) String() string

String returns the collector name as a string.

func (*CollectorName) UnmarshalJSON 

func (n *CollectorName) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler with validation.

func (*CollectorName) UnmarshalYAML 

func (n *CollectorName) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler with validation.

type ComponentKind 

type ComponentKind string

ComponentKind identifies the type of component. 

const (
	KindCollector ComponentKind = "collector"
	KindTool      ComponentKind = "tool"
	KindRemote    ComponentKind = "remote"
	KindUtility   ComponentKind = "utility"
)

func (ComponentKind) Plural 

func (k ComponentKind) Plural() string

Plural returns the plural form used in paths (collectors/tools/remotes/utilities).

func (ComponentKind) String 

func (k ComponentKind) String() string

String implements fmt.Stringer.

type DigestInfo 

type DigestInfo struct {
	// Digest is the expected SHA256 digest from the lockfile (empty if not pinned).
	Digest string

	// NeedsVerification is true if the component should be verified before execution.
	// Source-based components always need verification; PATH-based do not.
	NeedsVerification bool

	// IsSourceBased is true if this is a source-based component (not external or PATH).
	// Source-based components are installed via epack sync with Sigstore verification.
	IsSourceBased bool

	// MissingDigest is true if the component is in the lockfile but has no digest.
	// This can happen if the lockfile was created before digest pinning was implemented.
	MissingDigest bool

	// IsPATHBased is true if the component was discovered from PATH (unverified).
	// PATH-based components cannot be verified because they're not pinned.
	IsPATHBased bool

	// IsExternal is true if this is an external component (binary path in config).
	// External components can optionally be pinned in lockfile.
	IsExternal bool
}

DigestInfo contains information about a component's digest and verification state. This is used to determine whether TOCTOU-safe verification is required.

type EnvironmentName 

type EnvironmentName string

EnvironmentName is a validated environment name safe for filesystem paths. Can only be constructed via ParseEnvironmentName.

func MustParseEnvironmentName 

func MustParseEnvironmentName(name string) EnvironmentName

MustParseEnvironmentName parses an environment name, panicking on invalid input.

func ParseEnvironmentName 

func ParseEnvironmentName(name string) (EnvironmentName, error)

ParseEnvironmentName validates and returns an EnvironmentName.

func (EnvironmentName) String 

func (n EnvironmentName) String() string

String returns the environment name as a string.

func (*EnvironmentName) UnmarshalJSON 

func (n *EnvironmentName) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler with validation.

func (*EnvironmentName) UnmarshalYAML 

func (n *EnvironmentName) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler with validation.

type LockedPlatform 

type LockedPlatform struct {
	Digest string `yaml:"digest" json:"digest"`
	Asset  string `yaml:"asset,omitempty" json:"asset,omitempty"`
	URL    string `yaml:"url,omitempty" json:"url,omitempty"`
}

LockedPlatform pins per-platform digest information.

type LockedSigner 

type LockedSigner struct {
	Issuer              string `yaml:"issuer" json:"issuer"`
	Subject             string `yaml:"subject,omitempty" json:"subject,omitempty"`
	SourceRepositoryURI string `yaml:"source_repository_uri" json:"source_repository_uri"`
	SourceRepositoryRef string `yaml:"source_repository_ref" json:"source_repository_ref"`
}

LockedSigner captures required source signer identity claims.

func CopySigner 

func CopySigner(src *LockedSigner) *LockedSigner

CopySigner creates a defensive copy of a LockedSigner pointer.

type LockedUtility 

type LockedUtility struct {
	Source       string                    `yaml:"source,omitempty"`
	Version      string                    `yaml:"version,omitempty"`
	Signer       *LockedSigner             `yaml:"signer,omitempty"`
	ResolvedFrom *ResolvedFrom             `yaml:"resolved_from,omitempty"`
	Verification *Verification             `yaml:"verification,omitempty"`
	LockedAt     string                    `yaml:"locked_at,omitempty"`
	Platforms    map[string]LockedPlatform `yaml:"platforms"`
}

LockedUtility pins a user-installed utility. Utilities are global user tools installed via `epack install utility`. They use the same supply chain security model as other components.

type RemoteName 

type RemoteName string

RemoteName is a validated remote name safe for filesystem paths. Can only be constructed via ParseRemoteName.

func MustParseRemoteName 

func MustParseRemoteName(name string) RemoteName

MustParseRemoteName parses a remote name, panicking on invalid input.

func ParseRemoteName 

func ParseRemoteName(name string) (RemoteName, error)

ParseRemoteName validates and returns a RemoteName.

func (RemoteName) String 

func (n RemoteName) String() string

String returns the remote name as a string.

func (*RemoteName) UnmarshalJSON 

func (n *RemoteName) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler with validation.

func (*RemoteName) UnmarshalYAML 

func (n *RemoteName) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler with validation.

type ResolvedFrom 

type ResolvedFrom struct {
	Registry   string `yaml:"registry,omitempty" json:"registry,omitempty"`
	Descriptor string `yaml:"descriptor,omitempty" json:"descriptor,omitempty"`
}

ResolvedFrom captures where the component was resolved from.

func CopyResolvedFrom 

func CopyResolvedFrom(src *ResolvedFrom) *ResolvedFrom

CopyResolvedFrom creates a defensive copy of a ResolvedFrom pointer.

type ToolName 

type ToolName string

ToolName is a validated tool name safe for filesystem paths. Can only be constructed via ParseToolName.

func MustParseToolName 

func MustParseToolName(name string) ToolName

MustParseToolName parses a tool name, panicking on invalid input.

func ParseToolName 

func ParseToolName(name string) (ToolName, error)

ParseToolName validates and returns a ToolName.

func (ToolName) String 

func (n ToolName) String() string

String returns the tool name as a string.

func (*ToolName) UnmarshalJSON 

func (n *ToolName) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler with validation.

func (*ToolName) UnmarshalYAML 

func (n *ToolName) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler with validation.

type UtilityName 

type UtilityName string

UtilityName is a validated utility name safe for filesystem paths. Can only be constructed via ParseUtilityName.

func MustParseUtilityName 

func MustParseUtilityName(name string) UtilityName

MustParseUtilityName parses a utility name, panicking on invalid input.

func ParseUtilityName 

func ParseUtilityName(name string) (UtilityName, error)

ParseUtilityName validates and returns a UtilityName.

func (UtilityName) String 

func (n UtilityName) String() string

String returns the utility name as a string.

func (*UtilityName) UnmarshalJSON 

func (n *UtilityName) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler with validation.

func (*UtilityName) UnmarshalYAML 

func (n *UtilityName) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler with validation.

type Verification 

type Verification struct {
	Status     string `yaml:"status,omitempty" json:"status,omitempty"`
	VerifiedAt string `yaml:"verified_at,omitempty" json:"verified_at,omitempty"`
}

Verification captures the verification state at lock time.

func CopyVerification 

func CopyVerification(src *Verification) *Verification

CopyVerification creates a defensive copy of a Verification pointer.

type VerifyOptions 

type VerifyOptions struct {
	// Frozen requires all components to be pinned with digests (CI mode).
	// When true, any unpinned or unverified component causes an error.
	Frozen bool

	// InsecureAllowUnverified permits execution of components installed with
	// --insecure-skip-verify (signature verification was bypassed at install time).
	// SECURITY WARNING: Use only for development/testing.
	InsecureAllowUnverified bool

	// InsecureAllowUnpinned permits execution of components not pinned in lockfile.
	// This enables PATH discovery for components not configured in epack.yaml.
	// SECURITY WARNING: Use only for development/testing.
	InsecureAllowUnpinned bool
}

VerifyOptions controls component execution security. These options are shared across all component types (collectors, tools, remotes, utilities).

The security model follows the collector pattern:

  • By default, all components must be pinned in lockfile with digest verification
  • --frozen mode (CI) requires all components to be pinned
  • --insecure-allow-unverified permits components installed with --insecure-skip-verify
  • --insecure-allow-unpinned permits components not in lockfile (for development)

func DefaultVerifyOptions 

func DefaultVerifyOptions() VerifyOptions

DefaultVerifyOptions returns secure defaults for component verification. All security checks are enabled; no insecure modes allowed.

func VerifyOptionsFromEnv 

func VerifyOptionsFromEnv() VerifyOptions

VerifyOptionsFromEnv returns options with environment variable defaults applied. Reads EPACK_INSECURE_ALLOW_UNPINNED to set InsecureAllowUnpinned.

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.