Add guest, hooks, extract, and image/disk packages

Extract reusable packages from apiary and toolhive-appliance:

- guest/{boot,env,mount,netcfg,reaper,sshd}: Guest-side VM init
  packages with functional options for boot orchestration
- hooks/: Reusable RootFSHook builders with path traversal
  validation via internal/pathutil
- extract/: Embedded binary extraction cache with versioned
  caching, atomic writes, and cross-process locking
- image/disk/: Disk image download (with retry) and zstd+tar
  decompression reusing image/ tar security helpers
- net/egress/profiles: Permissive/Standard/Locked egress profiles
- internal/pathutil/: Shared path containment validation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JAORMX

extract/bundle.go

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package extract
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/gofrs/flock"
+)
+
+// File describes a single file to extract.
+type File struct {
+	Name    string
+	Content []byte
+	Mode    os.FileMode
+}
+
+// Symlink describes a symbolic link to create after extraction.
+type Symlink struct {
+	Target string // e.g. "libkrun.so.1"
+	Name   string // e.g. "libkrun.so"
+}
+
+// Bundle holds files and symlinks to extract into a versioned cache directory.
+type Bundle struct {
+	version string
+	files   []File
+	links   []Symlink
+	mu      sync.Mutex
+}
+
+// NewBundle creates a bundle with the given version string, files, and optional symlinks.
+func NewBundle(version string, files []File, links ...Symlink) *Bundle {
+	return &Bundle{version: version, files: files, links: links}
+}
+
+// Ensure extracts the bundle into a versioned subdirectory of cacheDir.
+// It returns the path to the directory containing the extracted files.
+// Extraction is skipped if a matching version already exists (cache hit).
+// Concurrent and cross-process safety is provided via in-process mutex
+// and cross-process file locking.
+func (b *Bundle) Ensure(cacheDir string) (string, error) {
+	hash := b.computeHash()
+	targetDir := filepath.Join(cacheDir, "extract-"+hash[:16])
+
+	// Fast path: check if already extracted.
+	if b.isValid(targetDir, hash) {
+		return targetDir, nil
+	}
+
+	// Acquire in-process mutex.
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	// Acquire cross-process file lock.
+	lockPath := filepath.Join(cacheDir, ".extract.lock")
+	if err := os.MkdirAll(cacheDir, 0o755); err != nil {
+		return "", fmt.Errorf("create cache dir: %w", err)
+	}
+	fl := flock.New(lockPath)
+	if err := fl.Lock(); err != nil {
+		return "", fmt.Errorf("acquire file lock: %w", err)
+	}
+	defer fl.Unlock() //nolint:errcheck // best-effort unlock
+
+	// Double-check after acquiring lock.
+	if b.isValid(targetDir, hash) {
+		return targetDir, nil
+	}
+
+	// Create temp dir in cacheDir for atomic swap.
+	tmpDir, err := os.MkdirTemp(cacheDir, "extract-tmp-")
+	if err != nil {
+		return "", fmt.Errorf("create temp dir: %w", err)
+	}
+	// Clean up temp dir on failure.
+	defer func() {
+		if err != nil {
+			_ = os.RemoveAll(tmpDir)
+		}
+	}()
+
+	// Extract all files.
+	for _, f := range b.files {
+		if extractErr := b.extractFile(tmpDir, f); extractErr != nil {
+			err = extractErr
+			return "", fmt.Errorf("extract %s: %w", f.Name, extractErr)
+		}
+	}
+
+	// Create symlinks.
+	for _, l := range b.links {
+		if linkErr := b.createSymlink(tmpDir, l); linkErr != nil {
+			err = linkErr
+			return "", fmt.Errorf("create symlink %s: %w", l.Name, linkErr)
+		}
+	}
+
+	// Write version file.
+	versionPath := filepath.Join(tmpDir, ".version")
+	if writeErr := os.WriteFile(versionPath, []byte(hash), 0o644); writeErr != nil {
+		err = writeErr
+		return "", fmt.Errorf("write version file: %w", writeErr)
+	}
+
+	// Atomic rename to target.
+	if renameErr := os.Rename(tmpDir, targetDir); renameErr != nil {
+		err = renameErr
+		return "", fmt.Errorf("rename to target: %w", renameErr)
+	}
+
+	return targetDir, nil
+}
+
+// computeHash returns a SHA-256 hex digest of the version string and all
+// file contents.
+func (b *Bundle) computeHash() string {
+	h := sha256.New()
+	h.Write([]byte(b.version))
+	for _, f := range b.files {
+		h.Write([]byte(f.Name))
+		h.Write(f.Content)
+	}
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+// isValid checks whether targetDir exists and contains a .version file
+// matching the expected hash.
+func (b *Bundle) isValid(targetDir, hash string) bool {
+	data, err := os.ReadFile(filepath.Join(targetDir, ".version"))
+	if err != nil {
+		return false
+	}
+	return string(data) == hash
+}
+
+// extractFile writes a single file atomically via a temp file and rename.
+func (b *Bundle) extractFile(dir string, f File) error {
+	dst := filepath.Join(dir, f.Name)
+	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		return fmt.Errorf("create parent dirs: %w", err)
+	}
+
+	// Write to temp file first, then rename for atomicity.
+	tmp, err := os.CreateTemp(filepath.Dir(dst), ".tmp-"+filepath.Base(f.Name)+"-")
+	if err != nil {
+		return fmt.Errorf("create temp file: %w", err)
+	}
+	tmpName := tmp.Name()
+
+	if _, err := tmp.Write(f.Content); err != nil {
+		_ = tmp.Close()
+		_ = os.Remove(tmpName)
+		return fmt.Errorf("write content: %w", err)
+	}
+	if err := tmp.Chmod(f.Mode); err != nil {
+		_ = tmp.Close()
+		_ = os.Remove(tmpName)
+		return fmt.Errorf("chmod: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		_ = os.Remove(tmpName)
+		return fmt.Errorf("close temp file: %w", err)
+	}
+	if err := os.Rename(tmpName, dst); err != nil {
+		_ = os.Remove(tmpName)
+		return fmt.Errorf("rename to final: %w", err)
+	}
+	return nil
+}
+
+// createSymlink creates a symbolic link in the given directory.
+func (b *Bundle) createSymlink(dir string, l Symlink) error {
+	linkPath := filepath.Join(dir, l.Name)
+	if err := os.Symlink(l.Target, linkPath); err != nil {
+		return fmt.Errorf("symlink %s -> %s: %w", l.Name, l.Target, err)
+	}
+	return nil
+}

extract/bundle_test.go

@@ -0,0 +1,172 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package extract
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBundle_Ensure_ExtractsFiles(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	files := []File{
+		{Name: "hello.txt", Content: []byte("hello"), Mode: 0o644},
+		{Name: "bin/tool", Content: []byte("#!/bin/sh"), Mode: 0o755},
+	}
+	b := NewBundle("v1", files)
+
+	dir, err := b.Ensure(cacheDir)
+	require.NoError(t, err)
+
+	// Verify file content.
+	got, err := os.ReadFile(filepath.Join(dir, "hello.txt"))
+	require.NoError(t, err)
+	assert.Equal(t, []byte("hello"), got)
+
+	// Verify binary content and permissions.
+	got, err = os.ReadFile(filepath.Join(dir, "bin", "tool"))
+	require.NoError(t, err)
+	assert.Equal(t, []byte("#!/bin/sh"), got)
+
+	info, err := os.Stat(filepath.Join(dir, "bin", "tool"))
+	require.NoError(t, err)
+	assert.Equal(t, os.FileMode(0o755), info.Mode().Perm())
+}
+
+func TestBundle_Ensure_Idempotent(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	files := []File{
+		{Name: "data.bin", Content: []byte("content"), Mode: 0o644},
+	}
+	b := NewBundle("v1", files)
+
+	dir1, err := b.Ensure(cacheDir)
+	require.NoError(t, err)
+
+	dir2, err := b.Ensure(cacheDir)
+	require.NoError(t, err)
+
+	assert.Equal(t, dir1, dir2)
+}
+
+func TestBundle_Ensure_VersionChange(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	files1 := []File{
+		{Name: "data.txt", Content: []byte("v1 content"), Mode: 0o644},
+	}
+	files2 := []File{
+		{Name: "data.txt", Content: []byte("v2 content"), Mode: 0o644},
+	}
+
+	b1 := NewBundle("v1", files1)
+	dir1, err := b1.Ensure(cacheDir)
+	require.NoError(t, err)
+
+	b2 := NewBundle("v2", files2)
+	dir2, err := b2.Ensure(cacheDir)
+	require.NoError(t, err)
+
+	assert.NotEqual(t, dir1, dir2)
+
+	// Verify each directory has its own content.
+	got1, err := os.ReadFile(filepath.Join(dir1, "data.txt"))
+	require.NoError(t, err)
+	assert.Equal(t, []byte("v1 content"), got1)
+
+	got2, err := os.ReadFile(filepath.Join(dir2, "data.txt"))
+	require.NoError(t, err)
+	assert.Equal(t, []byte("v2 content"), got2)
+}
+
+func TestBundle_Ensure_Symlinks(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	files := []File{
+		{Name: "libkrun.so.1", Content: []byte("library"), Mode: 0o755},
+	}
+	links := []Symlink{
+		{Target: "libkrun.so.1", Name: "libkrun.so"},
+	}
+	b := NewBundle("v1", files, links...)
+
+	dir, err := b.Ensure(cacheDir)
+	require.NoError(t, err)
+
+	// Verify symlink exists and points to the right target.
+	linkPath := filepath.Join(dir, "libkrun.so")
+	target, err := os.Readlink(linkPath)
+	require.NoError(t, err)
+	assert.Equal(t, "libkrun.so.1", target)
+
+	// Verify symlink resolves to correct content.
+	got, err := os.ReadFile(linkPath)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("library"), got)
+}
+
+func TestBundle_Ensure_EmptyBundle(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	b := NewBundle("v1", nil)
+
+	dir, err := b.Ensure(cacheDir)
+	require.NoError(t, err)
+
+	// Directory should exist with version file.
+	info, err := os.Stat(dir)
+	require.NoError(t, err)
+	assert.True(t, info.IsDir())
+
+	versionData, err := os.ReadFile(filepath.Join(dir, ".version"))
+	require.NoError(t, err)
+	assert.NotEmpty(t, versionData)
+}
+
+func TestBundle_Ensure_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	files := []File{
+		{Name: "shared.txt", Content: []byte("concurrent data"), Mode: 0o644},
+	}
+	b := NewBundle("v1", files)
+
+	const numGoroutines = 10
+	dirs := make([]string, numGoroutines)
+	errs := make([]error, numGoroutines)
+
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines)
+	for i := range numGoroutines {
+		go func(idx int) {
+			defer wg.Done()
+			dirs[idx], errs[idx] = b.Ensure(cacheDir)
+		}(i)
+	}
+	wg.Wait()
+
+	// All should succeed and return the same directory.
+	for i := range numGoroutines {
+		require.NoError(t, errs[i], "goroutine %d failed", i)
+		assert.Equal(t, dirs[0], dirs[i], "goroutine %d returned different dir", i)
+	}
+
+	// Verify file content is not corrupted.
+	got, err := os.ReadFile(filepath.Join(dirs[0], "shared.txt"))
+	require.NoError(t, err)
+	assert.Equal(t, []byte("concurrent data"), got)
+}

extract/doc.go

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package extract provides a cache-aware extraction mechanism for embedded
+// binary bundles. Consumers supply file contents as byte slices; the package
+// handles SHA-256 version keying, atomic directory swaps, cross-process file
+// locking, and symlink creation.
+package extract

extract/libname.go

@@ -0,0 +1,10 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package extract
+
+// LibName returns the platform-specific shared library filename for the
+// given base name and major version number.
+func LibName(base string, major int) string {
+	return libName(base, major)
+}

extract/libname_darwin.go

@@ -0,0 +1,10 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build darwin
+
+package extract
+
+func libName(base string, _ int) string {
+	return "lib" + base + ".dylib"
+}