dispatch

Documentation

Overview

Package dispatch implements TOCTOU-safe tool execution with verification.

This package implements Layer 2 (Execution) operations for tools:

• Parse wrapper flags (--pack, --output-dir, --json, --quiet)
• Resolve tool binary from lockfile
• Verify tool digest before execution
• Execute tool with proper protocol environment
• Capture and structure tool output

Package Structure

The package is organized into focused files:

• dispatch.go: Main entry points (Tool, dispatchVerifiedTool, dispatchToolFromPATH)
• flags.go: WrapperFlags parsing (domain logic)
• executor.go: Binary execution and environment setup (infrastructure)
• result.go: Result.json processing and backfill (domain logic)
• config.go: Config/lockfile loading and project root discovery

Security Boundary

This package MUST NOT import:

• internal/catalog (discovery layer - for display only)
• internal/cli (presentation layer)

Tool execution decisions (which binary to run, what digest to verify, what signer to trust) come exclusively from the lockfile. Catalog data is for discovery/display only and is handled at the CLI layer.

This boundary is enforced by the import guard test in dispatch_test.go.

Index

• func Tool(ctx context.Context, out Output, toolName string, args []string) error
• func ToolWithFlags(ctx context.Context, out Output, toolName string, toolArgs []string, ...) error
• type Output
• type StdOutput
  • func (StdOutput) Stderr() interface{ ... }
• type WrapperFlags
  • func ParseWrapperArgs(args []string) (WrapperFlags, []string, error)
  • func WrapperFlagsFromEnv() WrapperFlags

Functions

func Tool

func Tool(ctx context.Context, out Output, toolName string, args []string) error

Tool executes an external tool binary with security verification. This is a convenience wrapper that parses args internally. For CLI usage where flags are parsed in the command layer, use ToolWithFlags instead.

SECURITY: Tools get the same supply chain security as collectors: - Sigstore signature verification (at sync time) - Digest pinning in lockfile - TOCTOU-safe execution (copy-while-hash) - Restricted environment

func ToolWithFlags

func ToolWithFlags(ctx context.Context, out Output, toolName string, toolArgs []string, flags WrapperFlags) error

ToolWithFlags executes a tool with pre-parsed wrapper flags. This is the preferred entry point when the CLI layer handles flag parsing.

The context enables cancellation of long-running or hung tools. When the context is cancelled, the subprocess is terminated.

SECURITY: Tools get the same supply chain security as collectors: - Sigstore signature verification (at sync time) - Digest pinning in lockfile - TOCTOU-safe execution (copy-while-hash) - Restricted environment

Types

type Output

type Output interface {
	Stderr() interface{ Write([]byte) (int, error) }
}

Output provides an interface for writing dispatch output/errors. For warning/error messages, Stderr() is used. For tool execution, the actual tool process uses os.Stdout/os.Stderr directly.

type StdOutput

type StdOutput struct{}

StdOutput is the default Output implementation using os.Stderr.

func (StdOutput) Stderr

func (StdOutput) Stderr() interface{ Write([]byte) (int, error) }

type WrapperFlags

type WrapperFlags struct {
	PackPath              string // --pack <path>
	OutputDir             string // --output-dir <path>
	JSONMode              bool   // --json
	QuietMode             bool   // --quiet
	HasSeparator          bool   // true if "--" was used to separate wrapper args from tool args
	InsecureAllowUnpinned bool   // --insecure-allow-unpinned: allow unverified PATH execution
}

WrapperFlags holds parsed wrapper-level flags.

func ParseWrapperArgs

func ParseWrapperArgs(args []string) (WrapperFlags, []string, error)

ParseWrapperArgs separates wrapper flags from tool args.

Wrapper flags can be set via:

• CLI flags: --pack, --output-dir, --json, --quiet
• Environment variables: EPACK_PACK, EPACK_OUTPUT_DIR, EPACK_JSON, EPACK_QUIET
• Positional: first arg ending in .epack is treated as pack path

CLI flags take precedence over environment variables. Use "--" to explicitly end wrapper flags and pass remaining args to the tool. Without "--", wrapper flags are parsed until an unrecognized flag is encountered.

Returns (WrapperFlags, toolArgs, error)

func WrapperFlagsFromEnv

func WrapperFlagsFromEnv() WrapperFlags

WrapperFlagsFromEnv reads wrapper flags from environment variables. These provide defaults that can be overridden by CLI flags.