refactor(cli): rename operator command to tht

tools/tht/internal/safeio/files.go

@@ -0,0 +1,102 @@
+// Package safeio reads and writes local files without following symlinked path components.
+package safeio
+
+import (
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"unicode/utf8"
+)
+
+var ErrUnsafeFile = errors.New("unsafe file")
+
+// ValidateCanonicalPath rejects relative or lexically non-canonical paths before they are opened.
+func ValidateCanonicalPath(path string) error {
+	if !filepath.IsAbs(path) || filepath.Clean(path) != path || strings.Contains(path, string(filepath.Separator)+".."+string(filepath.Separator)) {
+		return ErrUnsafeFile
+	}
+	return nil
+}
+
+func readBoundedRegularFile(path string, file *os.File, maximum int64) ([]byte, error) {
+	if maximum < 0 || maximum == int64(^uint64(0)>>1) {
+		return nil, ErrUnsafeFile
+	}
+	info, err := file.Stat()
+	if err != nil || !info.Mode().IsRegular() || !hasSingleLink(info) {
+		return nil, ErrUnsafeFile
+	}
+	contents, err := io.ReadAll(io.LimitReader(file, maximum+1))
+	if err != nil || int64(len(contents)) > maximum {
+		return nil, ErrUnsafeFile
+	}
+	after, err := file.Stat()
+	if err != nil || !after.Mode().IsRegular() || !hasSingleLink(after) || !os.SameFile(info, after) {
+		return nil, ErrUnsafeFile
+	}
+	current, err := os.Stat(path)
+	if err != nil || !os.SameFile(info, current) {
+		return nil, ErrUnsafeFile
+	}
+	return contents, nil
+}
+
+func ReadCanonicalUTF8(path string, maximum int64) (string, error) {
+	contents, err := ReadCanonicalRegular(path, maximum)
+	if err != nil {
+		return "", err
+	}
+	if !utf8.Valid(contents) {
+		return "", ErrUnsafeFile
+	}
+	return string(contents), nil
+}
+
+func WriteCanonicalNewFile(path string, contents []byte, mode os.FileMode) error {
+	if err := ValidateCanonicalPath(path); err != nil {
+		return err
+	}
+	parent := filepath.Dir(path)
+	if err := requireCanonicalDirectory(parent); err != nil {
+		return err
+	}
+	if info, err := os.Lstat(path); err == nil {
+		if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 || info.Mode()&os.ModeType != 0 {
+			return ErrUnsafeFile
+		}
+		return ErrUnsafeFile
+	} else if !errors.Is(err, os.ErrNotExist) {
+		return ErrUnsafeFile
+	}
+	file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, mode)
+	if err != nil {
+		return ErrUnsafeFile
+	}
+	defer file.Close()
+	if _, err := file.Write(contents); err != nil {
+		_ = os.Remove(path)
+		return ErrUnsafeFile
+	}
+	if err := file.Sync(); err != nil {
+		_ = os.Remove(path)
+		return ErrUnsafeFile
+	}
+	return nil
+}
+
+func requireCanonicalDirectory(path string) error {
+	if err := ValidateCanonicalPath(path); err != nil {
+		return err
+	}
+	resolved, err := filepath.EvalSymlinks(path)
+	if err != nil || resolved != path {
+		return ErrUnsafeFile
+	}
+	info, err := os.Stat(path)
+	if err != nil || !info.IsDir() {
+		return ErrUnsafeFile
+	}
+	return nil
+}

tools/tht/internal/safeio/files_test.go

@@ -0,0 +1,95 @@
+package safeio
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/aritmolab/thothii/tools/tht/internal/testsupport"
+)
+
+func TestReadCanonicalRegularRejectsFinalAndParentSymlinks(t *testing.T) {
+	temporaryRoot, err := filepath.EvalSymlinks(os.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	root, err := os.MkdirTemp(temporaryRoot, "tht-safeio-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(root) })
+
+	realDirectory := filepath.Join(root, "real")
+	if err := os.Mkdir(realDirectory, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	realFile := filepath.Join(realDirectory, "secret")
+	if err := os.WriteFile(realFile, []byte("secret"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	parentLink := filepath.Join(root, "parent-link")
+	testsupport.SymlinkOrSkip(t, realDirectory, parentLink)
+	if _, err := ReadCanonicalRegular(filepath.Join(parentLink, "secret"), 1024); !errors.Is(err, ErrUnsafeFile) {
+		t.Fatalf("parent symlink error = %v, want ErrUnsafeFile", err)
+	}
+
+	finalLink := filepath.Join(root, "final-link")
+	testsupport.SymlinkOrSkip(t, realFile, finalLink)
+	if _, err := ReadCanonicalRegular(finalLink, 1024); !errors.Is(err, ErrUnsafeFile) {
+		t.Fatalf("final symlink error = %v, want ErrUnsafeFile", err)
+	}
+}
+
+func TestReadCanonicalUTF8RejectsNonUTF8AndHardlinks(t *testing.T) {
+	temporaryRoot, err := filepath.EvalSymlinks(os.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	root, err := os.MkdirTemp(temporaryRoot, "tht-safeio-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(root) })
+
+	nonUTF8 := filepath.Join(root, "annotations.yaml")
+	if err := os.WriteFile(nonUTF8, []byte{0xff, 0xfe, 0xfd}, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ReadCanonicalUTF8(nonUTF8, 1024); !errors.Is(err, ErrUnsafeFile) {
+		t.Fatalf("ReadCanonicalUTF8(nonUTF8) error = %v, want ErrUnsafeFile", err)
+	}
+
+	target := filepath.Join(root, "regular.txt")
+	if err := os.WriteFile(target, []byte("linked"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(root, "hardlink.txt")
+	if err := os.Link(target, link); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ReadCanonicalUTF8(link, 1024); !errors.Is(err, ErrUnsafeFile) {
+		t.Fatalf("ReadCanonicalUTF8(hardlink) error = %v, want ErrUnsafeFile", err)
+	}
+}
+
+func TestWriteCanonicalNewFileRejectsExistingTargets(t *testing.T) {
+	temporaryRoot, err := filepath.EvalSymlinks(os.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	root, err := os.MkdirTemp(temporaryRoot, "tht-safeio-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(root) })
+
+	path := filepath.Join(root, "artifact.yaml")
+	if err := os.WriteFile(path, []byte("existing"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := WriteCanonicalNewFile(path, []byte("new"), 0o600); !errors.Is(err, ErrUnsafeFile) {
+		t.Fatalf("WriteCanonicalNewFile(existing) error = %v, want ErrUnsafeFile", err)
+	}
+}

tools/tht/internal/safeio/files_unix.go

@@ -0,0 +1,57 @@
+//go:build !windows
+
+package safeio
+
+import (
+	"os"
+	"strings"
+
+	"golang.org/x/sys/unix"
+)
+
+// ReadCanonicalRegular opens an absolute canonical path component by component from the root
+// descriptor. O_NOFOLLOW rejects symlinks at every component, and the open directory descriptors
+// prevent later parent replacement from redirecting the final open.
+func ReadCanonicalRegular(path string, maximum int64) ([]byte, error) {
+	if err := ValidateCanonicalPath(path); err != nil {
+		return nil, err
+	}
+	components := strings.Split(strings.TrimPrefix(path, string(os.PathSeparator)), string(os.PathSeparator))
+	if len(components) == 0 || components[0] == "" {
+		return nil, ErrUnsafeFile
+	}
+
+	directory, err := unix.Open(string(os.PathSeparator), unix.O_RDONLY|unix.O_CLOEXEC|unix.O_DIRECTORY, 0)
+	if err != nil {
+		return nil, ErrUnsafeFile
+	}
+	directories := []int{directory}
+	defer func() { closeUnixDescriptors(directories) }()
+
+	for _, component := range components[:len(components)-1] {
+		nextDirectory, err := unix.Openat(directory, component, unix.O_RDONLY|unix.O_CLOEXEC|unix.O_DIRECTORY|unix.O_NOFOLLOW, 0)
+		if err != nil {
+			return nil, ErrUnsafeFile
+		}
+		directory = nextDirectory
+		directories = append(directories, directory)
+	}
+
+	descriptor, err := unix.Openat(directory, components[len(components)-1], unix.O_RDONLY|unix.O_CLOEXEC|unix.O_NOFOLLOW|unix.O_NONBLOCK, 0)
+	if err != nil {
+		return nil, ErrUnsafeFile
+	}
+	file := os.NewFile(uintptr(descriptor), "tht-safeio")
+	if file == nil {
+		unix.Close(descriptor)
+		return nil, ErrUnsafeFile
+	}
+	defer file.Close()
+	return readBoundedRegularFile(path, file, maximum)
+}
+
+func closeUnixDescriptors(descriptors []int) {
+	for _, descriptor := range descriptors {
+		unix.Close(descriptor)
+	}
+}

tools/tht/internal/safeio/files_unix_test.go

@@ -0,0 +1,32 @@
+//go:build !windows
+
+package safeio
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"golang.org/x/sys/unix"
+)
+
+func TestReadCanonicalRegularRejectsNamedPipeWithoutBlocking(t *testing.T) {
+	temporaryRoot, err := filepath.EvalSymlinks(os.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	root, err := os.MkdirTemp(temporaryRoot, "tht-safeio-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(root) })
+	pipe := filepath.Join(root, "secret-pipe")
+	if err := unix.Mkfifo(pipe, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := ReadCanonicalRegular(pipe, 1024); !errors.Is(err, ErrUnsafeFile) {
+		t.Fatalf("named pipe error = %v, want ErrUnsafeFile", err)
+	}
+}

tools/tht/internal/safeio/files_windows.go

@@ -0,0 +1,96 @@
+//go:build windows
+
+package safeio
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+
+	"golang.org/x/sys/windows"
+)
+
+const windowsRetainedHandleShareMode uint32 = windows.FILE_SHARE_READ | windows.FILE_SHARE_WRITE
+
+// ReadCanonicalRegular opens each component with FILE_FLAG_OPEN_REPARSE_POINT and rejects a
+// reparse point on the opened handle before opening the next component. Retained handles allow
+// ordinary read/write sharing but deny delete sharing, which blocks rename or deletion after a
+// component is opened and throughout the final read. Windows' Win32 API does not expose a
+// portable descriptor-relative equivalent of POSIX openat, so a hostile local actor can still
+// replace a not-yet-opened normal component between absolute-path opens. Installation directories
+// therefore need trusted local filesystem/ACL ownership on Windows.
+func ReadCanonicalRegular(path string, maximum int64) ([]byte, error) {
+	if err := ValidateCanonicalPath(path); err != nil {
+		return nil, err
+	}
+	volume := filepath.VolumeName(path)
+	root := volume + string(filepath.Separator)
+	components := strings.Split(strings.TrimPrefix(path, root), string(filepath.Separator))
+	if volume == "" || len(components) == 0 || components[0] == "" {
+		return nil, ErrUnsafeFile
+	}
+
+	current := root
+	parents := make([]windows.Handle, 0, len(components)-1)
+	defer func() { closeWindowsHandles(parents) }()
+	for _, component := range components[:len(components)-1] {
+		current = filepath.Join(current, component)
+		handle, err := openWindowsComponent(current, true)
+		if err != nil {
+			return nil, ErrUnsafeFile
+		}
+		parents = append(parents, handle)
+	}
+
+	current = filepath.Join(current, components[len(components)-1])
+	handle, err := openWindowsComponent(current, false)
+	if err != nil {
+		return nil, ErrUnsafeFile
+	}
+	file := os.NewFile(uintptr(handle), "tht-safeio")
+	if file == nil {
+		windows.CloseHandle(handle)
+		return nil, ErrUnsafeFile
+	}
+	defer file.Close()
+	return readBoundedRegularFile(path, file, maximum)
+}
+
+func openWindowsComponent(path string, directory bool) (windows.Handle, error) {
+	flags := uint32(windows.FILE_FLAG_OPEN_REPARSE_POINT)
+	if directory {
+		flags |= windows.FILE_FLAG_BACKUP_SEMANTICS
+	} else {
+		flags |= windows.FILE_ATTRIBUTE_NORMAL
+	}
+	handle, err := windows.CreateFile(
+		windows.StringToUTF16Ptr(path),
+		windows.GENERIC_READ,
+		windowsRetainedHandleShareMode,
+		nil,
+		windows.OPEN_EXISTING,
+		flags,
+		0,
+	)
+	if err != nil {
+		return 0, err
+	}
+	var information windows.ByHandleFileInformation
+	if err := windows.GetFileInformationByHandle(handle, &information); err != nil {
+		windows.CloseHandle(handle)
+		return 0, err
+	}
+	if information.FileAttributes&windows.FILE_ATTRIBUTE_REPARSE_POINT != 0 ||
+		(directory && information.FileAttributes&windows.FILE_ATTRIBUTE_DIRECTORY == 0) ||
+		(!directory && information.FileAttributes&windows.FILE_ATTRIBUTE_DIRECTORY != 0) {
+		windows.CloseHandle(handle)
+		return 0, ErrUnsafeFile
+	}
+	return handle, nil
+}
+
+func closeWindowsHandles(handles []windows.Handle) {
+	for _, handle := range handles {
+		windows.CloseHandle(handle)
+	}
+}

tools/tht/internal/safeio/files_windows_test.go

@@ -0,0 +1,68 @@
+//go:build windows
+
+package safeio
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"golang.org/x/sys/windows"
+)
+
+const expectedWindowsRetainedHandleShareMode = windows.FILE_SHARE_READ | windows.FILE_SHARE_WRITE
+
+// Keep this contract compile-enforced so Windows cross-test compilation catches a future
+// FILE_SHARE_DELETE regression even when the tests are compiled on a non-Windows host.
+var _ [windowsRetainedHandleShareMode - expectedWindowsRetainedHandleShareMode]struct{}
+var _ [expectedWindowsRetainedHandleShareMode - windowsRetainedHandleShareMode]struct{}
+
+func TestOpenWindowsComponentBlocksMutationWhileHandleIsRetained(t *testing.T) {
+	t.Run("parent rename", func(t *testing.T) {
+		parent := filepath.Join(t.TempDir(), "parent")
+		if err := os.Mkdir(parent, 0o700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(parent, "secret"), []byte("secret"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+
+		handle, err := openWindowsComponent(parent, true)
+		if err != nil {
+			t.Fatal(err)
+		}
+		renamed := parent + "-renamed"
+		if err := os.Rename(parent, renamed); err == nil {
+			windows.CloseHandle(handle)
+			t.Fatal("parent rename succeeded while its safe-I/O handle was retained")
+		}
+		if err := windows.CloseHandle(handle); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Rename(parent, renamed); err != nil {
+			t.Fatalf("parent rename after closing its safe-I/O handle: %v", err)
+		}
+	})
+
+	t.Run("final delete", func(t *testing.T) {
+		path := filepath.Join(t.TempDir(), "secret")
+		if err := os.WriteFile(path, []byte("secret"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+
+		handle, err := openWindowsComponent(path, false)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Remove(path); err == nil {
+			windows.CloseHandle(handle)
+			t.Fatal("final-file deletion succeeded while its safe-I/O handle was retained")
+		}
+		if err := windows.CloseHandle(handle); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Remove(path); err != nil {
+			t.Fatalf("final-file deletion after closing its safe-I/O handle: %v", err)
+		}
+	})
+}

tools/tht/internal/safeio/linkcount_unix.go

@@ -0,0 +1,13 @@
+//go:build !windows
+
+package safeio
+
+import (
+	"os"
+	"syscall"
+)
+
+func hasSingleLink(info os.FileInfo) bool {
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	return ok && stat.Nlink == 1
+}

tools/tht/internal/safeio/linkcount_windows.go

@@ -0,0 +1,9 @@
+//go:build windows
+
+package safeio
+
+import "os"
+
+func hasSingleLink(info os.FileInfo) bool {
+	return true
+}