lockfile

Documentation

Overview

Package lockfile provides lockfile parsing, serialization, and management.

The lockfile (epack.lock.yaml) pins component versions and digests for reproducible builds and supply chain security. It stores:

• Resolved component versions
• Per-platform digests for binary verification
• Signer identity (Sigstore certificate claims)
• Resolution metadata (which registry resolved the component)

Security features:

• YAML alias bomb detection (pre-parse)
• Size limits (DoS prevention)
• Name and version validation (path traversal prevention)
• Atomic writes with symlink protection (TOCTOU-safe)
• Deterministic serialization (consistent diffs)

Index

• Constants
• type LockFile
  • func Load(path string) (*LockFile, error)
  • func New() *LockFile
  • func Parse(data []byte) (*LockFile, error)
  • func (lf *LockFile) GetCollector(name string) (LockedCollector, bool)
  • func (lf *LockFile) GetComponentInfo(kind componenttypes.ComponentKind, name string) (LockedComponentInfo, bool)
  • func (lf *LockFile) GetComponentPlatformDigest(kind componenttypes.ComponentKind, name, platform string) (string, bool)
  • func (lf *LockFile) GetPlatformDigest(name, platform string) (string, bool)
  • func (lf *LockFile) GetRemote(name string) (LockedRemote, bool)
  • func (lf *LockFile) GetRemotePlatformDigest(name, platform string) (string, bool)
  • func (lf *LockFile) GetTool(name string) (LockedTool, bool)
  • func (lf *LockFile) GetToolPlatformDigest(name, platform string) (string, bool)
  • func (lf *LockFile) Save(path string) error
• type LockedCollector
• type LockedComponentInfo
• type LockedRemote
• type LockedTool

Constants

const FileName = "epack.lock.yaml"

FileName is the canonical lockfile filename for pinned collectors and tools.

Types

type LockFile

type LockFile struct {
	SchemaVersion int                        `yaml:"schema_version"`
	Collectors    map[string]LockedCollector `yaml:"collectors,omitempty"`
	Tools         map[string]LockedTool      `yaml:"tools,omitempty"`
	Remotes       map[string]LockedRemote    `yaml:"remotes,omitempty"`
}

LockFile is the v1 collector, tool, and remote adapter lockfile.

func Load

func Load(path string) (*LockFile, error)

Load reads lockfile from path. Enforces size and structural limits to prevent DoS attacks. SECURITY: Uses O_NOFOLLOW to refuse symlinks, preventing symlink-based attacks where an attacker could redirect lockfile reads to arbitrary files.

func New

func New() *LockFile

New returns an empty lockfile model.

func Parse

func Parse(data []byte) (*LockFile, error)

Parse parses and validates a lockfile from raw YAML data. Enforces size and structural limits to prevent DoS attacks.

func (*LockFile) GetCollector

func (lf *LockFile) GetCollector(name string) (LockedCollector, bool)

GetCollector returns a collector entry by logical name.

func (*LockFile) GetComponentInfo

func (lf *LockFile) GetComponentInfo(kind componenttypes.ComponentKind, name string) (LockedComponentInfo, bool)

GetComponentInfo returns a unified view of a component by kind and name. The returned Platforms map is a defensive copy to prevent callers from mutating the internal lockfile state.

func (*LockFile) GetComponentPlatformDigest

func (lf *LockFile) GetComponentPlatformDigest(kind componenttypes.ComponentKind, name, platform string) (string, bool)

GetComponentPlatformDigest returns a digest for component and platform key.

func (*LockFile) GetPlatformDigest

func (lf *LockFile) GetPlatformDigest(name, platform string) (string, bool)

GetPlatformDigest returns a digest for collector and platform key (os/arch).

func (*LockFile) GetRemote

func (lf *LockFile) GetRemote(name string) (LockedRemote, bool)

GetRemote returns a remote entry by logical name.

func (*LockFile) GetRemotePlatformDigest

func (lf *LockFile) GetRemotePlatformDigest(name, platform string) (string, bool)

GetRemotePlatformDigest returns a digest for remote and platform key (os/arch).

func (*LockFile) GetTool

func (lf *LockFile) GetTool(name string) (LockedTool, bool)

GetTool returns a tool entry by logical name.

func (*LockFile) GetToolPlatformDigest

func (lf *LockFile) GetToolPlatformDigest(name, platform string) (string, bool)

GetToolPlatformDigest returns a digest for tool and platform key (os/arch).

func (*LockFile) Save

func (lf *LockFile) Save(path string) error

Save writes lockfile to path atomically, refusing to follow symlinks. Uses TOCTOU-safe operations: symlink-safe directory creation and fd-pinned rename to prevent race conditions.

SECURITY: The path must be under the current working directory. Paths outside cwd are rejected to ensure all operations use the hardened fd-relative path.

type LockedCollector

type LockedCollector struct {
	Kind         string                                   `yaml:"kind,omitempty"` // "external" or empty for source-based
	Source       string                                   `yaml:"source,omitempty"`
	Version      string                                   `yaml:"version,omitempty"`
	Signer       *componenttypes.LockedSigner             `yaml:"signer,omitempty"`
	ResolvedFrom *componenttypes.ResolvedFrom             `yaml:"resolved_from,omitempty"`
	Verification *componenttypes.Verification             `yaml:"verification,omitempty"`
	LockedAt     string                                   `yaml:"locked_at,omitempty"`
	Platforms    map[string]componenttypes.LockedPlatform `yaml:"platforms"`
}

LockedCollector pins either a source-based or external collector entry.

type LockedComponentInfo

type LockedComponentInfo struct {
	Kind         string
	Source       string
	Version      string
	Signer       *componenttypes.LockedSigner
	ResolvedFrom *componenttypes.ResolvedFrom
	Verification *componenttypes.Verification
	LockedAt     string
	Platforms    map[string]componenttypes.LockedPlatform
}

LockedComponentInfo provides a unified view of locked component data. This enables generic handling of both collectors and tools.

type LockedRemote

type LockedRemote struct {
	Kind         string                                   `yaml:"kind,omitempty"` // "external" or empty for source-based
	Source       string                                   `yaml:"source,omitempty"`
	Version      string                                   `yaml:"version,omitempty"`
	Signer       *componenttypes.LockedSigner             `yaml:"signer,omitempty"`
	ResolvedFrom *componenttypes.ResolvedFrom             `yaml:"resolved_from,omitempty"`
	Verification *componenttypes.Verification             `yaml:"verification,omitempty"`
	LockedAt     string                                   `yaml:"locked_at,omitempty"`
	Platforms    map[string]componenttypes.LockedPlatform `yaml:"platforms"`
}

LockedRemote pins either a source-based or external remote adapter entry. Remote adapters use the same supply chain security model as collectors and tools.

type LockedTool

type LockedTool struct {
	Kind         string                                   `yaml:"kind,omitempty"` // "external" or empty for source-based
	Source       string                                   `yaml:"source,omitempty"`
	Version      string                                   `yaml:"version,omitempty"`
	Signer       *componenttypes.LockedSigner             `yaml:"signer,omitempty"`
	ResolvedFrom *componenttypes.ResolvedFrom             `yaml:"resolved_from,omitempty"`
	Verification *componenttypes.Verification             `yaml:"verification,omitempty"`
	LockedAt     string                                   `yaml:"locked_at,omitempty"`
	Platforms    map[string]componenttypes.LockedPlatform `yaml:"platforms"`
}

LockedTool pins either a source-based or external tool entry. Tools share the same structure as collectors since they use the same supply chain security model (Sigstore + digest verification).