Provisioning: Move apifmt, loki and safepath to provisioning app (#110226)

* Move apifmt

* Move safepath

* Move Loki package

* Regenerate Loki mock

* Missing file for Loki

apps/provisioning/pkg/safepath/dir.go

@@ -0,0 +1,65 @@
+package safepath
+
+import (
+	"fmt"
+	"path"
+	"strings"
+)
+
+// IsDir returns true if the filePath ends with a slash.
+// Empty string is considered a directory.
+func IsDir(filePath string) bool {
+	if filePath == "" || filePath == "." {
+		return true
+	}
+
+	return strings.HasSuffix(filePath, "/")
+}
+
+// Dir behaves exactly as path.Dir, but returns "" for the root directory.
+// and returns a trailing slash for all other directories.
+func Dir(filePath string) string {
+	if filePath == "" {
+		return ""
+	}
+
+	// Trim trailing slash before getting the directory
+	cleanPath := strings.TrimSuffix(filePath, "/")
+	dir := path.Dir(cleanPath)
+	if dir == "." || dir == "/" {
+		return ""
+	}
+
+	return dir + "/"
+}
+
+// InDir returns true if the filePath is a subdirectory of the given directory.
+func InDir(filePath, dir string) bool {
+	return strings.HasPrefix(filePath, dir)
+}
+
+// RelativeTo returns the relative path of the filePath to the given directory.
+// It handles cases where either filePath or dir have leading or trailing slashes.
+func RelativeTo(filePath, dir string) (string, error) {
+	if dir == "/" || dir == "" {
+		return filePath, nil
+	}
+
+	// Normalize paths by trimming leading and trailing slashes
+	normalizedDir := strings.Trim(dir, "/")
+	if normalizedDir != "" {
+		normalizedDir += "/"
+	}
+
+	normalizedPath := strings.TrimPrefix(filePath, "/")
+
+	// Check if the normalized path is in the normalized directory
+	if !strings.HasPrefix(normalizedPath, normalizedDir) {
+		return "", fmt.Errorf("filePath is not a subdirectory of dir")
+	}
+
+	// Get the relative path by trimming the directory prefix
+	relativePath := strings.TrimPrefix(normalizedPath, normalizedDir)
+
+	return relativePath, nil
+}

apps/provisioning/pkg/safepath/dir_test.go

@@ -0,0 +1,260 @@
+package safepath
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestIsFolderPath(t *testing.T) {
+	tests := []struct {
+		name     string
+		filePath string
+		want     bool
+	}{
+		{
+			name:     "empty path",
+			filePath: "",
+			want:     true,
+		},
+		{
+			name:     "dot path",
+			filePath: ".",
+			want:     true,
+		},
+		{
+			name:     "file path without extension",
+			filePath: "test",
+			want:     false,
+		},
+		{
+			name:     "file path with extension",
+			filePath: "test.json",
+			want:     false,
+		},
+		{
+			name:     "folder path with trailing slash",
+			filePath: "folder/",
+			want:     true,
+		},
+		{
+			name:     "nested folder path with trailing slash",
+			filePath: "folder/subfolder/",
+			want:     true,
+		},
+		{
+			name:     "file path in folder without trailing slash",
+			filePath: "folder/test.json",
+			want:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := IsDir(tt.filePath)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestDir(t *testing.T) {
+	tests := []struct {
+		name     string
+		filePath string
+		want     string
+	}{
+		{
+			name:     "empty path",
+			filePath: "",
+			want:     "",
+		},
+		{
+			name:     "root path",
+			filePath: "/",
+			want:     "",
+		},
+		{
+			name:     "single directory",
+			filePath: "folder",
+			want:     "",
+		},
+		{
+			name:     "nested directory",
+			filePath: "folder/subfolder",
+			want:     "folder/",
+		},
+		{
+			name:     "file in directory",
+			filePath: "folder/file.txt",
+			want:     "folder/",
+		},
+		{
+			name:     "multiple nested directories",
+			filePath: "folder/subfolder/subsubfolder",
+			want:     "folder/subfolder/",
+		},
+		{
+			name:     "directory with trailing slash",
+			filePath: "folder/subfolder/",
+			want:     "folder/",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := Dir(tt.filePath)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestInDir(t *testing.T) {
+	tests := []struct {
+		name     string
+		filePath string
+		dir      string
+		want     bool
+	}{
+		{
+			name:     "file in directory",
+			filePath: "folder/file.txt",
+			dir:      "folder/",
+			want:     true,
+		},
+		{
+			name:     "file not in directory",
+			filePath: "other/file.txt",
+			dir:      "folder/",
+			want:     false,
+		},
+		{
+			name:     "subdirectory",
+			filePath: "folder/subfolder/",
+			dir:      "folder/",
+			want:     true,
+		},
+		{
+			name:     "empty directory",
+			filePath: "folder/file.txt",
+			dir:      "",
+			want:     true,
+		},
+		{
+			name:     "exact match",
+			filePath: "folder/",
+			dir:      "folder/",
+			want:     true,
+		},
+		{
+			name:     "partial directory name match",
+			filePath: "folder2/file.txt",
+			dir:      "folder/",
+			want:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := InDir(tt.filePath, tt.dir)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestRelativeTo(t *testing.T) {
+	tests := []struct {
+		name        string
+		filePath    string
+		dir         string
+		want        string
+		expectError bool
+	}{
+		{
+			name:     "simple relative path",
+			filePath: "folder/subfolder/file.txt",
+			dir:      "folder",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "relative path with leading slash",
+			filePath: "/prefix/folder/subfolder/file.txt",
+			dir:      "/prefix/folder",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "relative path with leading slash in dir but in filePath",
+			filePath: "prefix/folder/subfolder/file.txt",
+			dir:      "/prefix/folder",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "with trailing slash in dir",
+			filePath: "folder/subfolder/file.txt",
+			dir:      "folder/",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "with trailing slash in both",
+			filePath: "folder/subfolder/",
+			dir:      "folder/",
+			want:     "subfolder/",
+		},
+		{
+			name:     "empty directory",
+			filePath: "file.txt",
+			dir:      "",
+			want:     "file.txt",
+		},
+		{
+			name:     "directory is root",
+			filePath: "folder/file.txt",
+			dir:      "/",
+			want:     "folder/file.txt",
+		},
+		{
+			name:     "nested directories",
+			filePath: "a/b/c/d/file.txt",
+			dir:      "a/b",
+			want:     "c/d/file.txt",
+		},
+		{
+			name:        "file not in directory",
+			filePath:    "other/file.txt",
+			dir:         "folder",
+			want:        "",
+			expectError: true,
+		},
+		{
+			name:        "file path shorter than directory",
+			filePath:    "file.txt",
+			dir:         "folder/subfolder",
+			want:        "",
+			expectError: true,
+		},
+		{
+			name:     "same directory",
+			filePath: "folder/file.txt",
+			dir:      "folder",
+			want:     "file.txt",
+		},
+		{
+			name:        "directory with similar prefix",
+			filePath:    "folder2/file.txt",
+			dir:         "folder",
+			want:        "",
+			expectError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := RelativeTo(tt.filePath, tt.dir)
+			if tt.expectError {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+				require.Equal(t, tt.want, got)
+			}
+		})
+	}
+}

apps/provisioning/pkg/safepath/path.go

@@ -0,0 +1,79 @@
+package safepath
+
+import (
+	"os"
+	"path"
+	"strings"
+)
+
+// TODO: explore if we want to use our own type for safepath
+// to make it clearer that this is a safe path and not a regular path
+
+// osSeparator is declared as a var here only to ensure we can change it in tests.
+var osSeparator = os.PathSeparator
+
+// Performs a [path.Clean] on the path, as well as replacing its OS separators.
+//
+// This replaces the OS separator with a slash.
+// All OSes we target (Linux, macOS, and Windows) support forward-slashes in path traversals, as such it's simpler to use the same character everywhere.
+// BSDs do as well (even though they're not a target as of writing).
+//
+// The output of a root path (i.e. absolute root or relative current dir) is always "" (empty string).
+func Clean(p string) string {
+	if osSeparator != '/' {
+		p = strings.ReplaceAll(p, string(osSeparator), "/")
+	}
+
+	cleaned := path.Clean(p)
+	if cleaned == "." || cleaned == "/" {
+		return ""
+	}
+	return cleaned
+}
+
+// Join is like path.Join but preserves trailing slashes from the last element
+func Join(elem ...string) string {
+	if len(elem) == 0 {
+		return ""
+	}
+
+	joined := path.Join(elem...)
+	// Preserve trailing slash if the last element had one
+	if strings.HasSuffix(elem[len(elem)-1], "/") {
+		return joined + "/"
+	}
+
+	return joined
+}
+
+// Base returns the last element of the path.
+func Base(p string) string {
+	b := path.Base(p)
+	if b == "." || b == "/" {
+		return ""
+	}
+
+	return b
+}
+
+// RemoveExt returns the path without the extension.
+// It should not remove the dot if the filename is e.g. `.gitignore`
+func RemoveExt(p string) string {
+	// Special case: if the file starts with a dot and has no other dots,
+	// it's a hidden file and should not have its "extension" removed
+	base := Base(p)
+	if strings.HasPrefix(base, ".") && strings.Count(base, ".") == 1 {
+		return p
+	}
+
+	ext := path.Ext(p)
+	if ext == "" {
+		return p
+	}
+
+	return p[0 : len(p)-len(ext)]
+}
+
+func IsAbs(p string) bool {
+	return path.IsAbs(p)
+}

apps/provisioning/pkg/safepath/path_test.go

@@ -0,0 +1,171 @@
+package safepath
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPathJoin(t *testing.T) {
+	testCases := []struct {
+		Comment string
+		In      []string
+		Out     any // string or error
+	}{
+		{"Empty elements should not change input", []string{"/test/"}, "/test/"},
+		{"Empty elements without leading slash should not change input", []string{"test/"}, "test/"},
+		{"Single element should be added to path", []string{"/test/", "abc"}, "/test/abc"},
+		{"Single element should be added to path with current dir prefix", []string{"./test/", "abc"}, "test/abc"},
+		{"Single element with leading slash should be added to path", []string{"/test/", "/abc"}, "/test/abc"},
+		{"Many elements are all appended to path", []string{"/test/", "a", "b", "c"}, "/test/a/b/c"},
+		{"Path traversal within same directory should be expanded", []string{"/test/", "a", "..", "b", ".", "..", "c"}, "/test/c"},
+		{"Complex path traversal remaining in prefix should be expanded", []string{"/test/", "a/..///c/", "../../test/d/"}, "/test/d/"},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.Comment, func(t *testing.T) {
+			path := Join(tc.In...)
+			if str, ok := tc.Out.(string); ok {
+				assert.Equal(t, str, path)
+			} else {
+				panic("expected out was neither string nor error")
+			}
+		})
+	}
+}
+
+func TestPathClean(t *testing.T) {
+	orig := osSeparator
+	osSeparator = '\\' // pretend we're on Windows
+	defer func() { osSeparator = orig }()
+
+	testCases := []struct {
+		Comment string
+		In      string
+		Out     string
+	}{
+		{"Simple path", "/test/", "/test"},
+		{"Simple path with OS separators", "\\test\\here", "/test/here"},
+		{"Simple path with mixed separators", "\\test/here", "/test/here"},
+		{"Path traversal within directory", "/test/abc/../def", "/test/def"},
+		{"Multiple path traversals", "/test/abc/../../def", "/def"},
+		{"Path traversal beyond root", "/test/../../../def", "/def"},
+		{"Complex path traversal with mixed separators", "\\test\\abc\\..\\..\\def/ghi\\..", "/def"},
+		{"Path traversal with multiple slashes", "/test////abc/..//def", "/test/def"},
+		{"Path traversal with current directory", "/test/./abc/../def/./ghi", "/test/def/ghi"},
+		{"Empty path segments with traversal", "//test//abc//..//def", "/test/def"},
+		{"Root path returns empty string", "/", ""},
+		{"Current directory returns empty string", ".", ""},
+		{"Path traversal to root returns empty string", "/test/..", ""},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.Comment, func(t *testing.T) {
+			assert.Equal(t, tc.Out, Clean(tc.In))
+		})
+	}
+}
+
+func TestBase(t *testing.T) {
+	testCases := []struct {
+		name     string
+		path     string
+		expected string
+	}{
+		{
+			name:     "empty path",
+			path:     "",
+			expected: "",
+		},
+		{
+			name:     "root path",
+			path:     "/",
+			expected: "",
+		},
+		{
+			name:     "current directory",
+			path:     ".",
+			expected: "",
+		},
+		{
+			name:     "simple filename",
+			path:     "file.txt",
+			expected: "file.txt",
+		},
+		{
+			name:     "path with directory",
+			path:     "/path/to/file.txt",
+			expected: "file.txt",
+		},
+		{
+			name:     "path with trailing slash",
+			path:     "/path/to/dir/",
+			expected: "dir",
+		},
+		{
+			name:     "hidden file",
+			path:     ".gitignore",
+			expected: ".gitignore",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result := Base(tc.path)
+			assert.Equal(t, tc.expected, result)
+		})
+	}
+}
+
+func TestRemoveExt(t *testing.T) {
+	testCases := []struct {
+		name     string
+		path     string
+		expected string
+	}{
+		{
+			name:     "empty path",
+			path:     "",
+			expected: "",
+		},
+		{
+			name:     "no extension",
+			path:     "filename",
+			expected: "filename",
+		},
+		{
+			name:     "simple extension",
+			path:     "file.txt",
+			expected: "file",
+		},
+		{
+			name:     "multiple dots",
+			path:     "file.tar.gz",
+			expected: "file.tar",
+		},
+		{
+			name:     "hidden file",
+			path:     ".gitignore",
+			expected: ".gitignore",
+		},
+		{
+			name:     "path with directory",
+			path:     "/path/to/file.txt",
+			expected: "/path/to/file",
+		},
+		{
+			name:     "path with trailing slash",
+			path:     "/path/to/dir/",
+			expected: "/path/to/dir/",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result := RemoveExt(tc.path)
+			assert.Equal(t, tc.expected, result)
+		})
+	}
+}

apps/provisioning/pkg/safepath/safe.go

@@ -0,0 +1,116 @@
+package safepath
+
+import (
+	"errors"
+	"regexp"
+	"strings"
+)
+
+var (
+	ErrPathTooLong          = errors.New("path too long")
+	ErrInvalidCharacters    = errors.New("path contains invalid characters")
+	ErrDoubleSlash          = errors.New("path contains double slashes")
+	ErrInvalidFormat        = errors.New("invalid path format")
+	ErrPercentChar          = errors.New("path contains percent character which could be used for URL encoding attacks")
+	ErrHiddenPath           = errors.New("path contains hidden file or directory (starting with dot)")
+	ErrPathTraversalAttempt = errors.New("path contains traversal attempt (./ or ../)")
+)
+
+const (
+	MaxPathLength = 1024 // Maximum allowed path length in characters
+)
+
+// validPathPattern matches valid path characters:
+// - Alphanumeric (a-z, A-Z, 0-9)
+// - Forward slash for path separation
+// - Dots for file extensions and current directory
+// - Underscores and hyphens for file/folder names
+var validPathPattern = regexp.MustCompile(`^[a-zA-Z0-9 /_.-]+$`)
+
+func IsSafe(path string) error {
+	// Check path length
+	if len(path) > MaxPathLength {
+		return ErrPathTooLong
+	}
+
+	// Empty path is valid (represents current directory)
+	if path == "" {
+		return nil
+	}
+
+	// Check specifically for percent character first
+	if strings.Contains(path, "%") {
+		return ErrPercentChar
+	}
+
+	// Check for invalid characters
+	if !validPathPattern.MatchString(path) {
+		return ErrInvalidCharacters
+	}
+
+	// Check for double slashes
+	if strings.Contains(path, "//") {
+		return ErrDoubleSlash
+	}
+
+	parts := Split(path)
+	for _, part := range parts {
+		// Check for path traversal attempts first
+		if part == ".." || part == "." {
+			return ErrPathTraversalAttempt
+		}
+
+		// Check for hidden files/directories in any part of the path
+		if part == "" || strings.HasPrefix(part, ".") {
+			return ErrHiddenPath
+		}
+	}
+
+	// If it's not a directory, it should have a filename component
+	if !IsDir(path) && len(parts) > 0 {
+		filename := parts[len(parts)-1]
+		if filename == "" {
+			return ErrInvalidFormat
+		}
+	}
+
+	return nil
+}
+
+// SafeSegment returns a safe part of the path
+// It ensures the path is free from traversal attempts, hidden files,
+// and other potentially dangerous patterns.
+func SafeSegment(path string) string {
+	if path == "" {
+		return ""
+	}
+
+	parts := Split(path)
+	if len(parts) == 0 {
+		return ""
+	}
+
+	// Build up the path segment by segment, checking safety
+	var safePath string
+	for _, part := range parts {
+		// Check if this segment is safe
+		testPath := Join(safePath, part)
+		if IsSafe(testPath) != nil || part == "" {
+			// If this segment is unsafe, return the path up to but not including this segment
+			// Add trailing slash for directories
+			if safePath != "" {
+				return safePath + "/"
+			}
+			return ""
+		}
+		safePath = testPath
+	}
+
+	// If we made it through all segments, the path is safe
+	// Preserve trailing slash if original path had one
+	if IsDir(path) && safePath != "" {
+		return safePath + "/"
+	}
+
+	return safePath
+}

apps/provisioning/pkg/safepath/safe_test.go

@@ -0,0 +1,303 @@
+package safepath
+
+import (
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestIsSafe(t *testing.T) {
+	tests := []struct {
+		name    string
+		path    string
+		wantErr error
+	}{
+		// Valid paths
+		{
+			name:    "valid simple path",
+			path:    "path/to/resource",
+			wantErr: nil,
+		},
+		{
+			name:    "character space",
+			path:    "path/to/my file.json",
+			wantErr: nil,
+		},
+		{
+			name:    "valid path with extension",
+			path:    "path/to/file.json",
+			wantErr: nil,
+		},
+		{
+			name:    "valid directory path with trailing slash",
+			path:    "path/to/folder/",
+			wantErr: nil,
+		},
+		{
+			name:    "valid path with allowed special chars",
+			path:    "my-path/to_file/resource.json",
+			wantErr: nil,
+		},
+		{
+			name:    "empty path",
+			path:    "",
+			wantErr: nil,
+		},
+		{
+			name:    "path at max length",
+			path:    strings.Repeat("a", MaxPathLength),
+			wantErr: nil,
+		},
+		{
+			name:    "valid directory",
+			path:    "path/to/",
+			wantErr: nil,
+		},
+		{
+			name:    "valid path with dots in filename",
+			path:    "path/to/file.min.js",
+			wantErr: nil,
+		},
+		// Length and depth limits
+		{
+			name:    "path too long",
+			path:    strings.Repeat("a/", 512) + "file", // Creates path > MaxPathLength
+			wantErr: ErrPathTooLong,
+		},
+		// Invalid characters and formats
+		{
+			name:    "invalid special character hash",
+			path:    "path/to/file#.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "invalid character backslash",
+			path:    "path\\to\\file.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "invalid character question mark",
+			path:    "path/to/file?.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "invalid character asterisk",
+			path:    "path/to/*.json",
+			wantErr: ErrInvalidCharacters,
+		},
+
+		// Double slashes
+		{
+			name:    "double slashes in middle",
+			path:    "path//to/file.json",
+			wantErr: ErrDoubleSlash,
+		},
+		{
+			name:    "double slashes at start",
+			path:    "//path/to/file.json",
+			wantErr: ErrDoubleSlash,
+		},
+		{
+			name:    "double slashes at end",
+			path:    "path/to/file//",
+			wantErr: ErrDoubleSlash,
+		},
+
+		// Hidden files and directories
+		{
+			name:    "hidden file",
+			path:    "path/to/.hidden",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden directory",
+			path:    "path/to/.git/",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden file with extension",
+			path:    "path/to/.gitignore",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden path component in middle",
+			path:    "path/.hidden/file.json",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden path at root",
+			path:    ".env/config.json",
+			wantErr: ErrHiddenPath,
+		},
+
+		// Path traversal attempts
+		{
+			name:    "path traversal with parent directory",
+			path:    "path/to/../file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "path traversal at start",
+			path:    "../path/file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "path traversal with multiple levels",
+			path:    "path/../../file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "path traversal at end",
+			path:    "path/to/folder/../",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "single dot path component",
+			path:    "path/to/./file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "double dot path component",
+			path:    "path/to/../",
+			wantErr: ErrPathTraversalAttempt,
+		},
+
+		// Current directory references
+		{
+			name:    "current directory at start",
+			path:    "./path/file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "current directory in middle",
+			path:    "path/./file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "current directory at end",
+			path:    "path/to/./",
+			wantErr: ErrPathTraversalAttempt,
+		},
+
+		// URL encoding attempts
+		{
+			name:    "percent character in filename",
+			path:    "path/to/%20file.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded slash",
+			path:    "path/to%2Ffile.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded dot",
+			path:    "path/to%2E%2E/file.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded path traversal",
+			path:    "path/to/%2e%2e/file.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded null byte",
+			path:    "path/to/file%00.json",
+			wantErr: ErrPercentChar,
+		},
+
+		// Mixed invalid patterns
+		{
+			name:    "mixed traversal attempts",
+			path:    "./path/../file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "mixed special chars and traversal",
+			path:    "../path/#/file.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "mixed percent and special chars",
+			path:    "path/%20/#/file.json",
+			wantErr: ErrPercentChar,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := IsSafe(tt.path)
+			if !errors.Is(err, tt.wantErr) {
+				t.Errorf("IsSafe() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestSafeSegment(t *testing.T) {
+	tests := []struct {
+		name     string
+		path     string
+		wantPath string
+	}{
+		{
+			name:     "empty path",
+			path:     "",
+			wantPath: "",
+		},
+		{
+			name:     "simple valid path",
+			path:     "path/to/file.txt",
+			wantPath: "path/to/file.txt",
+		},
+		{
+			name:     "path with valid special characters",
+			path:     "my-path/some_file/test.json",
+			wantPath: "my-path/some_file/test.json",
+		},
+		{
+			name:     "path with trailing slash",
+			path:     "path/to/folder/",
+			wantPath: "path/to/folder/",
+		},
+		{
+			name:     "path with multiple extensions",
+			path:     "path/to/file.min.js",
+			wantPath: "path/to/file.min.js",
+		},
+		{
+			name:     "path with invalid characters",
+			path:     "path/to/file#.txt",
+			wantPath: "path/to/",
+		},
+		{
+			name:     "path with traversal attempt",
+			path:     "path/../file.txt",
+			wantPath: "path/",
+		},
+		{
+			name:     "path with hidden file",
+			path:     "path/to/.hidden",
+			wantPath: "path/to/",
+		},
+		{
+			name:     "path with percent character",
+			path:     "path/to/%20file.txt",
+			wantPath: "path/to/",
+		},
+		{
+			name:     "path with double slashes",
+			path:     "path//to/file.txt",
+			wantPath: "path/",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotPath := SafeSegment(tt.path)
+			if gotPath != tt.wantPath {
+				t.Errorf("SafeSegment() = %v, want %v", gotPath, tt.wantPath)
+			}
+		})
+	}
+}

apps/provisioning/pkg/safepath/trie.go

@@ -0,0 +1,98 @@
+// Package safepath provides utilities for safe path handling and validation
+// through a trie-based implementation.
+package safepath
+
+import (
+	"fmt"
+)
+
+// trieNode represents a single node in the trie data structure.
+type trieNode struct {
+	children map[string]*trieNode
+	isDir    bool // marks if this node represents a directory
+}
+
+// Trie implements a trie data structure for efficient path lookups and validation.
+type Trie struct {
+	root *trieNode
+}
+
+// NewTrie creates and returns a new initialized Trie.
+func NewTrie() *Trie {
+	return &Trie{
+		root: &trieNode{
+			children: make(map[string]*trieNode),
+		},
+	}
+}
+
+// Add inserts a path into the trie. It returns an error if there's a conflict
+// between the path types (file vs directory) or if the path is invalid.
+func (t *Trie) Add(path string) error {
+	if path == "" || path == "/" {
+		return nil
+	}
+
+	current := t.root
+	segments := Split(path)
+
+	var accumulatedPath string
+	for i, segment := range segments {
+		accumulatedPath = Join(accumulatedPath, segment)
+		if current.children == nil {
+			current.children = make(map[string]*trieNode)
+		}
+
+		isLastSegment := i == len(segments)-1
+		node, exists := current.children[segment]
+		if !exists {
+			node = &trieNode{
+				children: make(map[string]*trieNode),
+			}
+			current.children[segment] = node
+		} else {
+			if (!isLastSegment && !node.isDir) || (isLastSegment && !node.isDir && IsDir(path)) {
+				return fmt.Errorf("path %q exists but is not a directory", accumulatedPath)
+			}
+
+			if isLastSegment && node.isDir && !IsDir(path) {
+				return fmt.Errorf("path %q exists but is not a file", accumulatedPath)
+			}
+		}
+
+		current = node
+		current.isDir = !isLastSegment || IsDir(path)
+	}
+
+	return nil
+}
+
+// Exists checks if a path exists in the trie and matches its expected type (file/directory).
+func (t *Trie) Exists(path string) bool {
+	if path == "" || path == "/" {
+		return true
+	}
+
+	current := t.root
+	segments := Split(path)
+
+	for i, segment := range segments {
+		if current.children == nil {
+			return false
+		}
+
+		next, exists := current.children[segment]
+		if !exists {
+			return false
+		}
+
+		current = next
+		isLastSegment := i == len(segments)-1
+
+		if isLastSegment {
+			return current.isDir == IsDir(path)
+		}
+	}
+
+	return false
+}

apps/provisioning/pkg/safepath/trie_test.go

@@ -0,0 +1,125 @@
+package safepath
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestTrie(t *testing.T) {
+	tests := []struct {
+		name          string
+		pathsToAdd    []string
+		pathsToCheck  []string
+		expectedExist []bool
+		expectedError error
+	}{
+		{
+			name:          "empty trie",
+			pathsToAdd:    []string{},
+			pathsToCheck:  []string{"test", "test/"},
+			expectedExist: []bool{false, false},
+			expectedError: nil,
+		},
+		{
+			name:          "single file",
+			pathsToAdd:    []string{"test.json"},
+			pathsToCheck:  []string{"test.json", "test.json/"},
+			expectedExist: []bool{true, false},
+			expectedError: nil,
+		},
+		{
+			name:          "single directory",
+			pathsToAdd:    []string{"test/"},
+			pathsToCheck:  []string{"test", "test/"},
+			expectedExist: []bool{false, true},
+			expectedError: nil,
+		},
+		{
+			name:          "nested structure",
+			pathsToAdd:    []string{"folder/", "folder/file.txt", "folder/subfolder/", "folder/subfolder/test.json"},
+			pathsToCheck:  []string{"folder/", "folder/file.txt", "folder/file.txt/", "folder/subfolder/", "folder/subfolder/test.json", "folder/subfolder/test.json/"},
+			expectedExist: []bool{true, true, false, true, true, false},
+			expectedError: nil,
+		},
+		{
+			name:          "partial paths",
+			pathsToAdd:    []string{"a/b/c/d/"},
+			pathsToCheck:  []string{"a/", "a/b/", "a/b/c/", "a/b/c/d/"},
+			expectedExist: []bool{true, true, true, true},
+			expectedError: nil,
+		},
+		{
+			name:          "file in middle of path",
+			pathsToAdd:    []string{"a/file.txt", "a/file.txt/b/"},
+			pathsToCheck:  []string{},
+			expectedExist: []bool{},
+			expectedError: fmt.Errorf("path %q exists but is not a directory", "a/file.txt"),
+		},
+		{
+			name:          "empty path",
+			pathsToAdd:    []string{""},
+			pathsToCheck:  []string{""},
+			expectedExist: []bool{true},
+			expectedError: nil,
+		},
+		{
+			name:          "root directory",
+			pathsToAdd:    []string{"/"},
+			pathsToCheck:  []string{"/", ""},
+			expectedExist: []bool{true, true},
+			expectedError: nil,
+		},
+		{
+			name:          "duplicate paths",
+			pathsToAdd:    []string{"test/", "test/"},
+			pathsToCheck:  []string{"test/"},
+			expectedExist: []bool{true},
+			expectedError: nil,
+		},
+		{
+			name:          "file to directory conversion not allowed",
+			pathsToAdd:    []string{"test.txt", "test.txt/file.txt"},
+			pathsToCheck:  []string{},
+			expectedExist: []bool{},
+			expectedError: fmt.Errorf("path %q exists but is not a directory", "test.txt"),
+		},
+		{
+			name:          "directory to file conversion not allowed",
+			pathsToAdd:    []string{"test/", "test"},
+			pathsToCheck:  []string{},
+			expectedExist: []bool{},
+			expectedError: fmt.Errorf("path %q exists but is not a file", "test"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			trie := NewTrie()
+
+			// Add paths
+			var lastErr error
+			for _, path := range tt.pathsToAdd {
+				err := trie.Add(path)
+				if err != nil {
+					lastErr = err
+					break
+				}
+			}
+
+			if tt.expectedError != nil {
+				require.Error(t, lastErr)
+				require.Equal(t, tt.expectedError.Error(), lastErr.Error())
+				return
+			}
+			require.NoError(t, lastErr)
+
+			// Check existence
+			for i, path := range tt.pathsToCheck {
+				exists := trie.Exists(path)
+				require.Equal(t, tt.expectedExist[i], exists, "path: %s", path)
+			}
+		})
+	}
+}

apps/provisioning/pkg/safepath/walk.go

@@ -0,0 +1,65 @@
+package safepath
+
+import (
+	"context"
+	"path"
+	"sort"
+	"strings"
+)
+
+type WalkFunc = func(ctx context.Context, path string) error
+
+// Walk walks the given folder path and calls the given function for each folder.
+func Walk(ctx context.Context, p string, fn WalkFunc) error {
+	if p == "." || p == "/" {
+		return nil
+	}
+
+	var currentPath string
+	for _, folder := range strings.Split(p, "/") {
+		if folder == "" {
+			// Trailing / leading slash?
+			continue
+		}
+
+		currentPath = path.Join(currentPath, folder)
+		if err := fn(ctx, currentPath); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// Depth returns the depth of the given path.
+func Depth(p string) int {
+	return len(Split(p))
+}
+
+// Split splits the given path into segments.
+func Split(p string) []string {
+	trimmed := strings.Trim(p, "/")
+	if trimmed == "" {
+		return []string{}
+	}
+	return strings.Split(trimmed, "/")
+}
+
+// SortByDepth will sort any resource, by its path depth. You must pass in
+// a way to get said path. Ties are alphabetical by default.
+func SortByDepth[T any](items []T, pathExtractor func(T) string, asc bool) {
+	sort.Slice(items, func(i, j int) bool {
+		pathI, pathJ := pathExtractor(items[i]), pathExtractor(items[j])
+		depthI, depthJ := Depth(pathI), Depth(pathJ)
+
+		if depthI == depthJ {
+			// alphabetical by default if depth is the same
+			return pathI < pathJ
+		}
+
+		if asc {
+			return depthI < depthJ
+		}
+		return depthI > depthJ
+	})
+}

apps/provisioning/pkg/safepath/walk_test.go

@@ -0,0 +1,231 @@
+package safepath
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWalk(t *testing.T) {
+	tests := []struct {
+		name          string
+		path          string
+		expectedPaths []string
+		expectError   bool
+	}{
+		{
+			name: "simple path",
+			path: "a/b/c",
+			expectedPaths: []string{
+				"a",
+				"a/b",
+				"a/b/c",
+			},
+		},
+		{
+			name: "path with leading slash",
+			path: "/a/b/c",
+			expectedPaths: []string{
+				"a",
+				"a/b",
+				"a/b/c",
+			},
+		},
+		{
+			name: "path with trailing slash",
+			path: "a/b/c/",
+			expectedPaths: []string{
+				"a",
+				"a/b",
+				"a/b/c",
+			},
+		},
+		{
+			name:          "root path",
+			path:          "/",
+			expectedPaths: nil,
+		},
+		{
+			name:          "current directory",
+			path:          ".",
+			expectedPaths: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var paths []string
+			err := Walk(context.Background(), tt.path, func(ctx context.Context, p string) error {
+				paths = append(paths, p)
+				return nil
+			})
+
+			if tt.expectError {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.expectedPaths, paths)
+			}
+		})
+	}
+}
+
+func TestDepth(t *testing.T) {
+	tests := []struct {
+		name          string
+		path          string
+		expectedDepth int
+	}{
+		{
+			name:          "empty path",
+			path:          "",
+			expectedDepth: 0,
+		},
+		{
+			name:          "root path",
+			path:          "/",
+			expectedDepth: 0,
+		},
+		{
+			name:          "single level",
+			path:          "a",
+			expectedDepth: 1,
+		},
+		{
+			name:          "multiple levels",
+			path:          "a/b/c",
+			expectedDepth: 3,
+		},
+		{
+			name:          "path with leading slash",
+			path:          "/a/b/c",
+			expectedDepth: 3,
+		},
+		{
+			name:          "path with trailing slash",
+			path:          "a/b/c/",
+			expectedDepth: 3,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			depth := Depth(tt.path)
+			assert.Equal(t, tt.expectedDepth, depth)
+		})
+	}
+}
+
+func TestSplit(t *testing.T) {
+	tests := []struct {
+		name             string
+		path             string
+		expectedSegments []string
+	}{
+		{
+			name:             "empty path",
+			path:             "",
+			expectedSegments: []string{},
+		},
+		{
+			name:             "root path",
+			path:             "/",
+			expectedSegments: []string{},
+		},
+		{
+			name:             "single segment",
+			path:             "a",
+			expectedSegments: []string{"a"},
+		},
+		{
+			name:             "multiple segments",
+			path:             "a/b/c",
+			expectedSegments: []string{"a", "b", "c"},
+		},
+		{
+			name:             "path with leading slash",
+			path:             "/a/b/c",
+			expectedSegments: []string{"a", "b", "c"},
+		},
+		{
+			name:             "path with trailing slash",
+			path:             "a/b/c/",
+			expectedSegments: []string{"a", "b", "c"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			segments := Split(tt.path)
+			assert.Equal(t, tt.expectedSegments, segments)
+		})
+	}
+}
+
+func TestWalkError(t *testing.T) {
+	expectedErr := errors.New("test error")
+	err := Walk(context.Background(), "a/b/c", func(ctx context.Context, p string) error {
+		if p == "a/b" {
+			return expectedErr
+		}
+		return nil
+	})
+
+	require.ErrorIs(t, err, expectedErr)
+}
+
+func TestSortByDepth(t *testing.T) {
+	tests := []struct {
+		name     string
+		asc      bool
+		paths    []string
+		expected []string
+	}{
+		{
+			name:     "ascending sort (shallowest first)",
+			paths:    []string{"a/b/c", "a", "a/b", "d/e/f/g"},
+			asc:      true,
+			expected: []string{"a", "a/b", "a/b/c", "d/e/f/g"},
+		},
+		{
+			name:     "descending sort with alphabetical tie-break",
+			paths:    []string{"a/b/c", "a", "a/b", "d/e/f/g", "x/y/z"},
+			asc:      false,
+			expected: []string{"d/e/f/g", "a/b/c", "x/y/z", "a/b", "a"},
+		},
+		{
+			name:     "paths with empty string",
+			paths:    []string{"a/b/c", "", "a", "a/b"},
+			asc:      true,
+			expected: []string{"", "a", "a/b", "a/b/c"},
+		},
+		{
+			name:     "paths with trailing slashes",
+			paths:    []string{"a/b/", "a/b/c", "b/", "a/", "a"},
+			asc:      true,
+			expected: []string{"a", "a/", "b/", "a/b/", "a/b/c"},
+		},
+		{
+			name:     "single path",
+			paths:    []string{"a/b/c"},
+			expected: []string{"a/b/c"},
+		},
+		{
+			name:     "empty paths",
+			paths:    []string{},
+			expected: []string{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			paths := make([]string, len(tt.paths))
+			copy(paths, tt.paths)
+			SortByDepth(paths, func(s string) string { return s }, tt.asc)
+			assert.Equal(t, tt.expected, paths)
+		})
+	}
+}